Example for the Bridge

[Previous] [Next] [Up]

This example demonstrate how to render a scene using the Bridge.

New Topics

• Implementation of Bridge jobs
• Running a Bridge server
• Using a Bridge server

Detailed Description

Implementation of Bridge jobs

This first example below shows how to implement a Bridge job. It starts with a DB element used by the job, followed by the client-side and server-side implementation of the job.

The client-side version of the job implements the interface mi::bridge::IClient_job. In particular the methods serialize(), receive_remote_result(), and get_references() are important here. Here, we simply transfer the input tag to the server and receive the computed result.

The server-side version implements the interface mi::bridge::IServer_job. Note that both classes use the same UUID to establish the relation between client- and server-side version. The method deserialize() is the counterpart to serialize of the client-side job. The serialization at the end of execute() is the counterpart to receive_remote_result() on the client-side job.

Running a Bridge server

This second example below shows how to run a Bridge server. The interface mi::bridge::IBridge_server allows to create a Bridge application. To configure such an application you need at least to set the directory that should be used for the local disk cache. To do anything useful with such an application you need to register all job, i.e., the server-side version of the job.

Finally, you need to call mi::bridge::IApplication::open() to actually start the Bridge server. It then accepts jobs from a Bridge client, executes them and returns the result.

Using a Bridge server

The third example below shows how to use a Bridge server. After creating two elements in the database we use the API component mi::bridge::IBridge_client to open a Bridge session. An instance of mi::bridge::IClient_session_state_callback registered with the session which allows to wait for the actual connection to the server to complete.

Next we create a client scope and client transaction. The client transaction is connected to the regular transaction and establishes the database context for the Bridge. The client transaction is then used to execute our Bridge job. The Bridge then uses mi::bridge::IClient_job::get_references() and mi::neuraylib::IElement::get_references() to figure out which DB elements need to be replicated or updated on the Bridge server before the job can be executed.

Example Source

Source Code Location: examples/example_bridge.h

/******************************************************************************
 * Copyright 2024 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
// examples/example_bridge.h
//
// Definitions of My_serializable, My_referencing_element, My_bridge_job_clientside, and
// My_bridge_job_serverside.
 
#ifndef EXAMPLE_BRIDGE_H
#define EXAMPLE_BRIDGE_H
 
#include <sstream>
#include <string>
 
#include <mi/dice.h>
 
#include "example_element_and_job.h"
 
 
// Converts a number of bytes into a human-readable string.
std::string bytes_to_string( mi::Size size)
{
    char buffer[256];
    if( size > 1048576)
        snprintf( buffer, sizeof( buffer)-1, "%.1f MB", static_cast<mi::Float64>( size)/1048576.0);
    else if( size > 1024)
        snprintf( buffer, sizeof( buffer)-1, "%.1f kB", static_cast<mi::Float64>( size)/1024.0);
    else
        snprintf( buffer, sizeof( buffer)-1, "%llu bytes", size);
    return buffer;
}
 
// A serializable which stores one mi::Uint64 values.
class My_serializable : public mi::base::Interface_implement<mi::neuraylib::ISerializable>
{
public:
    My_serializable( mi::Uint64 data = 0) : m_data( data) { }
 
    mi::Uint64 get_data() const { return m_data; }
 
    typedef mi::base::Uuid_t<0xc10b4a48,0xcf64,0x4355,0x9d,0x12,0xc7,0x71,0x9e,0xee,0x4c,0x93> IID;
 
    mi::base::Uuid get_class_id() const { return IID(); }
 
    void serialize( mi::neuraylib::ISerializer* serializer) const { serializer->write( &m_data); }
 
    void deserialize( mi::neuraylib::IDeserializer* deserializer) { deserializer->read( &m_data); }
 
private:
    mi::Uint64 m_data;
};
 
// A database element that references another database element and a serializable.
class My_referencing_element
  : public mi::neuraylib::Element<0xfbbab662,0x91e6,0x4712,0x92,0xa0,0x0c,0xa6,0x74,0xb9,0xb0,0x0b>
{
public:
    My_referencing_element( mi::neuraylib::Tag tag = mi::neuraylib::NULL_TAG, mi::Uint64 data = 0)
      : m_tag( tag), m_serializable( new My_serializable( data)) { }
 
    void serialize( mi::neuraylib::ISerializer* serializer) const
    {
        serializer->write( &m_tag);
        serializer->serialize( m_serializable.get());
    }
 
    void deserialize( mi::neuraylib::IDeserializer* deserializer)
    {
        deserializer->read( &m_tag);
        m_serializable = static_cast<My_serializable*>(
            deserializer->deserialize<mi::neuraylib::ISerializable>());
    }
 
    void get_references( mi::neuraylib::ITag_set* result) const
    {
        if( m_tag)
            result->add_tag( m_tag);
    }
 
    mi::neuraylib::IElement* copy() const { return new My_referencing_element( *this); }
 
    const char* get_class_name() const { return "My_referencing_element"; }
 
    mi::neuraylib::Tag get_tag() const { return m_tag; }
 
    void set_tag( mi::neuraylib::Tag tag) { m_tag = tag; }
 
    const My_serializable* get_serializable() const
    {
        m_serializable->retain();
        return m_serializable.get();
    }
 
private:
    mi::neuraylib::Tag m_tag;
    mi::base::Handle<My_serializable> m_serializable;
};
 
// The client-side version of a Bridge job that asks the Bridge server to access a database element
// identified by the tag, to follow the reference, and to call get_data() on that element. It
// returns the sum of the return values of that call and the get_data() calls of the serializables
// in the accessed database element and this job.
class My_bridge_job_clientside : public
    mi::bridge::Client_job<0xc6822a21,0x45c7,0x448d,0x95,0x52,0x73,0xe6,0xfa,0x62,0xa3,0x60>
{
public:
    My_bridge_job_clientside(
        mi::neuraylib::Tag input_tag = mi::neuraylib::NULL_TAG,  mi::Uint64 data = 0)
      : m_input_tag( input_tag), m_serializable( new My_serializable( data)), m_result( 0) { }
 
    virtual void serialize( mi::neuraylib::ISerializer* serializer) const
    {
        serializer->write( &m_input_tag);
        serializer->serialize( m_serializable.get());
    }
 
    void receive_remote_result( mi::neuraylib::IDeserializer* deserializer, bool /*last_result*/)
    {
        deserializer->read( &m_result);
        m_condition.signal();
    }
 
    void get_references( mi::neuraylib::ITag_set* result) const
    {
        if( m_input_tag)
            result->add_tag( m_input_tag);
    }
 
    void get_references( mi::bridge::IElement_set* /*result*/) const { }
 
    void progress_callback( mi::bridge::IClient_job_progress* job_progress);
 
    void error_callback( mi::Sint32 error_code, const char* error_message)
    {
        fprintf( stderr, "Error while executing job, error code: %d, error message: %s",
            error_code, error_message);
        m_condition.signal();
    }
 
    void wait() { m_condition.wait(); }
 
    mi::Uint64 get_result() const { return m_result; }
 
private:
    mi::neuraylib::Tag m_input_tag;
    mi::base::Handle<My_serializable> m_serializable;
    mi::Uint64 m_result;
    mi::base::Condition m_condition;
};
 
void My_bridge_job_clientside::progress_callback( mi::bridge::IClient_job_progress* job_progress)
{
    mi::bridge::Client_job_state client_job_state = job_progress->get_state();
 
    if( client_job_state == mi::bridge::CLIENT_JOB_DETECTING_CHANGES) {
 
        fprintf( stderr, "Bridge detecting changes: %llu modified element(s) detected.\n",
            job_progress->get_updated_element_count());
 
    } else if( client_job_state == mi::bridge::CLIENT_JOB_PREPARING) {
 
        fprintf( stderr, "Bridge calculating hashes: %llu pending calculation(s), %s uploaded.\n",
            job_progress->get_pending_hash_calculation_count(),
            bytes_to_string( job_progress->get_uploaded_cache_miss_bytes()).c_str());
 
    } else if( client_job_state == mi::bridge::CLIENT_JOB_QUERYING_CACHE_STATUS) {
 
        fprintf( stderr, "Bridge querying cache status: %llu pending request(s), %s uploaded.\n",
            job_progress->get_pending_cache_status_count(),
            bytes_to_string( job_progress->get_uploaded_cache_miss_bytes()).c_str());
 
    } else if( client_job_state == mi::bridge::CLIENT_JOB_UPLOADING) {
 
        if( job_progress->get_pending_data_serialization_count() > 0) {
            mi::Float64 total_progress = 100.0
                * static_cast<mi::Float64>( job_progress->get_uploaded_cache_miss_bytes())
                / static_cast<mi::Float64>( job_progress->get_cache_miss_bytes());
            fprintf( stderr, "Bridge upload: %s/%s (%.0lf%%) total - data serialization for "
                "%llu element(s) pending.\n",
                bytes_to_string( job_progress->get_uploaded_cache_miss_bytes()).c_str(),
                bytes_to_string( job_progress->get_cache_miss_bytes()).c_str(),
                total_progress,
                job_progress->get_pending_data_serialization_count());
        } else {
            mi::Float64 total_progress = 100.0
                * static_cast<mi::Float64>( job_progress->get_uploaded_cache_miss_bytes())
                / static_cast<mi::Float64>( job_progress->get_cache_miss_bytes());
            mi::Float64 element_progress = 100.0
                * static_cast<mi::Float64>(
                    job_progress->get_currently_uploaded_element_uploaded_bytes())
                / static_cast<mi::Float64>( job_progress->get_currently_uploaded_element_size());
            const char* name = job_progress->get_currently_uploaded_element_name();
            std::stringstream s;
            if( name)
                s <<  "\"" << name << "\"";
            else
                s << "unnamed element";
            fprintf( stderr, "Bridge upload: %s/%s (%.0lf%%) total - %s/%s (%.0lf%%) for %s.\n",
                bytes_to_string( job_progress->get_uploaded_cache_miss_bytes()).c_str(),
                bytes_to_string( job_progress->get_cache_miss_bytes()).c_str(),
                total_progress,
                bytes_to_string(
                    job_progress->get_currently_uploaded_element_uploaded_bytes()).c_str(),
                bytes_to_string( job_progress->get_currently_uploaded_element_size()).c_str(),
                element_progress,
                s.str().c_str());
        }
 
    } else if( client_job_state == mi::bridge::CLIENT_JOB_PENDING) {
 
        fprintf( stderr, "Bridge waiting for server to finish processing the upload.\n");
 
    } else if( client_job_state == mi::bridge::CLIENT_JOB_DONE) {
 
        fprintf( stderr, "Bridge upload completed.\n");
 
    }
}
 
// The server-side version of a Bridge job that accesses a database element identified by the tag,
// follows the reference, and calls get_data() called on that element. It returns the sum of the
// return values of that call and the get_data() calls of the serializables in the accessed database
// element and this job.
class My_bridge_job_serverside : public
    mi::bridge::Server_job<0xc6822a21,0x45c7,0x448d,0x95,0x52,0x73,0xe6,0xfa,0x62,0xa3,0x60>
{
public:
    virtual void deserialize( mi::neuraylib::IDeserializer* deserializer)
    {
        deserializer->read( &m_input_tag);
        m_serializable = static_cast<My_serializable*>(
            deserializer->deserialize<mi::neuraylib::ISerializable>());
    }
 
    void execute(
        mi::bridge::IServer_transaction* server_transaction,
        mi::neuraylib::ISerializer* serializer, mi::bridge::IServer_job_info*)
    {
        mi::base::Handle<mi::neuraylib::IDice_transaction> dice_transaction(
            server_transaction->get_database_transaction<mi::neuraylib::IDice_transaction>());
        mi::base::Handle<const My_referencing_element> referencing_element(
            dice_transaction->access<My_referencing_element>( m_input_tag));
        mi::base::Handle<const My_element> element(
            dice_transaction->access<My_element>( referencing_element->get_tag()));
        mi::Uint64 element_data = element->get_data();
        mi::base::Handle<const My_serializable> serializable(
            referencing_element->get_serializable());
        mi::Uint64 serializable_data = serializable->get_data();
        mi::Uint64 job_serializable_data = m_serializable->get_data();
        mi::Uint64 result = element_data + serializable_data + job_serializable_data;
        serializer->write( &result);
    }
 
private:
    mi::neuraylib::Tag m_input_tag;
    mi::base::Handle<My_serializable> m_serializable;
};
 
#endif // EXAMPLE_BRIDGE_H

Source Code Location: examples/example_bridge_server.cpp

/******************************************************************************
 * Copyright 2023 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
// examples/example_bridge_server.cpp
//
// Starts a DiCE Bridge server and accepts requests to execute a simple test job.
//
// The example expects the following command line argument:
//
//   example_bridge_server <disk_cache_path> <bridge_server_address> <application_path>
//                         <security_token> [<ssl_cert_file> <ssl_private_key_file> <ssl_password>]
//
// disk_cache_path        directory where the server can cache uploaded elements
// bridge_server_address  address of the Bridge server, e.g., 0.0.0.0:8998
// application_path       the application path used by the server, e.g., "/dice"
// security_token         security token to be provided by clients
// ssl_cert_file          file containing the server's SSL certificate
// ssl_priv_key_file      file containing the server's private key
// ssl_password           password for decrypting the server's private key
 
#include <iostream>
 
#include <mi/dice.h>
 
// Include code shared by all examples.
#include "example_shared.h"
// Include code for DB element My_element.
#include "example_element_and_job.h"
// Include code for DB element My_referencing_element and the Bridge job.
#include "example_bridge.h"
 
// An application session handler that accepts all sessions that provide a given security token.
class Application_session_handler
  : public mi::base::Interface_implement<mi::bridge::IApplication_session_handler>
{
public:
    Application_session_handler( const std::string& security_token)
      : m_security_token( security_token) { }
 
    bool on_session_connect( mi::bridge::IServer_session* session)
    {
        const char* security_token = session->get_security_token();
        return security_token && m_security_token == security_token;
 
    }
private:
    std::string m_security_token;
};
 
// Register the serializable classes.
void configuration( mi::neuraylib::INeuray* neuray)
{
    // Register the classes My_element and My_referencing_element with DiCE.
    mi::base::Handle<mi::neuraylib::IDice_configuration> dice_configuration(
        neuray->get_api_component<mi::neuraylib::IDice_configuration>());
    check_success( dice_configuration.is_valid_interface());
    check_success( dice_configuration->register_serializable_class<My_element>());
    check_success( dice_configuration->register_serializable_class<My_referencing_element>());
    check_success( dice_configuration->register_serializable_class<My_serializable>());
}
 
void run(
    mi::neuraylib::INeuray* neuray,
    const char* disk_cache_path,
    const char* bridge_server_address,
    const char* application_path,
    const char* security_token,
    const char* ssl_cert_file,
    const char* ssl_private_key_file,
    const char* ssl_password)
{
    // Start the HTTP server handling the Bridge connection using webSockets.
    mi::base::Handle<mi::http::IFactory> http_factory(
        neuray->get_api_component<mi::http::IFactory>());
    mi::base::Handle<mi::http::IServer> http_server( http_factory->create_server());
    if( ssl_cert_file && ssl_private_key_file && ssl_password)
        http_server->start_ssl(
            bridge_server_address, ssl_cert_file, ssl_private_key_file, ssl_password);
    else
        http_server->start( bridge_server_address);
 
    // Access the API component for the Bridge server and create and application.
    mi::base::Handle<mi::bridge::IBridge_server> bridge_server(
        neuray->get_api_component<mi::bridge::IBridge_server>());
    mi::base::Handle<mi::bridge::IApplication> application(
        bridge_server->create_application( application_path, http_server.get()));
 
    if( application.is_valid_interface()) {
 
        // Configure the application.
        application->set_disk_cache( disk_cache_path);
        application->register_job<My_bridge_job_serverside>();
        mi::base::Handle<mi::bridge::IApplication_session_handler> application_session_handler(
            new Application_session_handler( security_token));
        check_success( application->set_session_handler(
            application_session_handler.get()) == 0);
 
        // Run the application for some fixed time.
        application->open();
        sleep_seconds( 60);
        application->close();
    }
 
    http_server->shutdown();
}
 
int main( int argc, char* argv[])
{
    // Collect command line parameters
    if( argc != 5 && argc != 8) {
        std::cerr << "Usage: example_bridge_server <disk_cache_path> <bridge_server_address> \\\n"
                  << "           <application_path> <security_token> [<ssl_cert_file> \\\n"
                  << "           <ssl_private_key_file> <ssl_password>]" << std::endl;
        keep_console_open();
        return EXIT_FAILURE;
    }
    const char* disk_cache_path       = argv[1];
    const char* bridge_server_address = argv[2];
    const char* application_path      = argv[3];
    const char* security_token        = argv[4];
    const char* ssl_cert_file         = argc >= 8 ? argv[5] : 0;
    const char* ssl_private_key_file  = argc >= 8 ? argv[6] : 0;
    const char* ssl_password          = argc >= 8 ? argv[7] : 0;
 
    // Access the neuray library
    mi::base::Handle<mi::neuraylib::INeuray> neuray( load_and_get_ineuray());
    check_success( neuray.is_valid_interface());
 
    // Configure the neuray library
    configuration( neuray.get());
 
    // Start the neuray library
    mi::Sint32 result = neuray->start();
    check_start_success( result);
 
    // Listen to Bridge clients
    run( neuray.get(), disk_cache_path, bridge_server_address, application_path, security_token,
        ssl_cert_file, ssl_private_key_file, ssl_password);
 
    // Shut down the neuray library
    check_success( neuray->shutdown() == 0);
    neuray = 0;
 
    // Unload the neuray library
    check_success( unload());
 
    keep_console_open();
    return EXIT_SUCCESS;
}

Source Code Location: examples/example_bridge_client.cpp

/******************************************************************************
 * Copyright 2023 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
// examples/example_bridge_client.cpp
//
// Connects to a DiCE Bridge server and executes a simple test job.
//
// The example expects the following command line argument:
//
//   example_bridge_client <bridge_server_url> <security_token>
//
// bridge_server_url  URL of the Bridge server, e.g., ws://127.0.0.1:8998/dice (no SSL) or
//                    wss://127.0.0.1:8998/dice (SSL)
// security_token     security token to authenticate against the server
 
#include <iostream>
 
#include <mi/dice.h>
 
// Include code shared by all examples.
#include "example_shared.h"
// Include code for DB element My_element.
#include "example_element_and_job.h"
// Include code for DB element My_referencing_element and the Bridge job.
#include "example_bridge.h"
 
// A simple implementation of a client session state callback that allows to wait for the first
// state change and to check whether the session is connected to the server.
class Client_session_state_callback
    : public mi::base::Interface_implement<mi::bridge::IClient_session_state_callback>
{
public:
    Client_session_state_callback() : m_connected( false) { }
 
    void session_state_callback( mi::bridge::Client_session_state state)
    {
        m_connected = state == mi::bridge::CLIENT_SESSION_CONNECTED;
        m_condition.signal();
    }
 
    void wait() { m_condition.wait(); }
 
    bool get_connected() const { return m_connected; }
 
private:
    bool m_connected;
    mi::base::Condition m_condition;
};
 
// Register the serializable classes.
void configuration( mi::neuraylib::INeuray* neuray)
{
    // Register the classes My_element and My_referencing_element with DiCE.
    mi::base::Handle<mi::neuraylib::IDice_configuration> dice_configuration(
        neuray->get_api_component<mi::neuraylib::IDice_configuration>());
    check_success( dice_configuration.is_valid_interface());
    check_success( dice_configuration->register_serializable_class<My_element>());
    check_success( dice_configuration->register_serializable_class<My_referencing_element>());
    check_success( dice_configuration->register_serializable_class<My_serializable>());
}
 
void run( mi::neuraylib::INeuray* neuray, const char* bridge_server_url, const char* security_token)
{
    // Get the database, the global scope of the database and create a transaction in the global
    // scope.
    mi::base::Handle<mi::neuraylib::IDatabase> database(
        neuray->get_api_component<mi::neuraylib::IDatabase>());
    check_success( database.is_valid_interface());
    mi::base::Handle<mi::neuraylib::IScope> scope( database->get_global_scope());
    mi::base::Handle<mi::neuraylib::IDice_transaction> dice_transaction(
        scope->create_transaction<mi::neuraylib::IDice_transaction>());
    check_success( dice_transaction.is_valid_interface());
 
    // Create a database element.
    mi::base::Handle<My_element> element( new My_element( 42));
    mi::neuraylib::Tag element_tag
        = dice_transaction->store( element.get(), mi::neuraylib::Tag());
    check_success( element_tag);
    element = 0;
 
    // Create database element referencing the first one.
    mi::base::Handle<My_referencing_element> referencing_element(
        new My_referencing_element( element_tag, 43));
    mi::neuraylib::Tag referencing_element_tag
        = dice_transaction->store( referencing_element.get(), mi::neuraylib::Tag());
    check_success( referencing_element_tag);
    referencing_element = 0;
 
    // Connect to the Bridge server.
    mi::base::Handle<mi::bridge::IBridge_client> bridge_client(
        neuray->get_api_component<mi::bridge::IBridge_client>());
    mi::base::Handle<mi::bridge::IClient_session> client_session(
        bridge_client->get_session( bridge_server_url, security_token));
 
    mi::base::Handle<Client_session_state_callback> client_session_state_callback(
        new Client_session_state_callback());
    client_session->add_session_state_callback( client_session_state_callback.get());
    client_session_state_callback->wait();
 
    if( client_session_state_callback->get_connected()) {
 
        // Create the DB context for the Bridge.
        mi::base::Handle<mi::neuraylib::ITransaction> transaction(
            dice_transaction->get_interface<mi::neuraylib::ITransaction>());
 
        // Execute a job accessing the referencing database element.
        mi::base::Handle<My_bridge_job_clientside> bridge_job(
            new My_bridge_job_clientside( referencing_element_tag, 44));
        mi::Sint32 result = client_session->execute( bridge_job.get(), transaction.get());
        check_success( result == 0);
        bridge_job->wait();
        check_success( bridge_job->get_result() == 42 + 43 + 44);
    }
    client_session_state_callback = 0;
 
    dice_transaction->commit();
}
 
int main( int argc, char* argv[])
{
    // Collect command line parameters
    if( argc != 3) {
        std::cerr << "Usage: example_bridge_client <bridge_server_url> <security_token>"
                  << std::endl;
        keep_console_open();
        return EXIT_FAILURE;
    }
    const char* bridge_server_url = argv[1];
    const char* security_token    = argv[2];
 
    // Access the neuray library
    mi::base::Handle<mi::neuraylib::INeuray> neuray( load_and_get_ineuray());
    check_success( neuray.is_valid_interface());
 
    // Configure the neuray library
    configuration( neuray.get());
 
    // Start the neuray library
    mi::Sint32 result = neuray->start();
    check_start_success( result);
 
    run( neuray.get(), bridge_server_url, security_token);
 
    // Shut down the neuray library
    check_success( neuray->shutdown() == 0);
    neuray = 0;
 
    // Unload the neuray library
    check_success( unload());
 
    keep_console_open();
    return EXIT_SUCCESS;
}

[Previous] [Next] [Up]