DiCE API nvidia_logo_transpbg.gif Up
mi::neuraylib::INode_manager_cluster Class Referenceabstract

The interface to a cluster created and managed by the node manager. More...

#include <inode_manager.h>

Inheritance diagram for mi::neuraylib::INode_manager_cluster:

Public Types

enum  Cluster_status {
  CLUSTER_ESTABLISHED = 0 ,
  CLUSTER_SHUTDOWN = 1 ,
  CLUSTER_FAILURE = 2 ,
  CLUSTER_FORCE_32_BIT = 0xffffffffU
}
 Possible cluster states. More...
 
- Public Types inherited from mi::base::Interface_declare< 0x0a58b727, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0> IID
 Declares the interface ID (IID) of this interface. More...
 

Public Member Functions

virtual const ICluster_descriptorget_cluster_descriptor () const =0
 Returns the cluster descriptor for the cluster. More...
 
virtual Cluster_status get_cluster_status () const =0
 Returns the status of the cluster. More...
 
virtual void set_timeout (Float64 timeout)=0
 Sets the keep-alive timeout for the cluster. More...
 
virtual Sint32 set_cluster_property (const char *name, const char *value)=0
 Sets a cluster property. More...
 
virtual Sint32 remove_cluster_property (const char *name)=0
 Removes a cluster property. More...
 
virtual Sint32 start_worker_program (const char *program_name, const char *argument_string, Uint32 child_process_timeout=0)=0
 Starts a worker program if none has been started when the cluster has been created. More...
 
virtual Sint32 shutdown_worker_program ()=0
 Shuts down the program that was started on all worker nodes when the cluster was created. More...
 
virtual Sint32 restart_worker_program ()=0
 Restarts the program that is supposed to run on all workers. More...
 
virtual void shutdown ()=0
 Initiates the shutdown of the cluster. More...
 
virtual IWorker_node_descriptorget_head_node ()=0
 Returns the head node. More...
 
virtual void add_worker_property_callback (IWorker_node_property_callback *callback)=0
 Adds a callback to be called when a property of a worker node changes. More...
 
virtual void remove_worker_property_callback (IWorker_node_property_callback *callback)=0
 Removes a previously added callback for property changes of worker nodes. More...
 
virtual void add_cluster_property_callback (ICluster_property_callback *callback)=0
 Adds a callback to be called when a cluster property changes. More...
 
virtual void remove_cluster_property_callback (ICluster_property_callback *callback)=0
 Removes a previously added callback for cluster property changes. More...
 
virtual void add_worker_node_callback (IWorker_node_callback *callback)=0
 Adds a callback to be called when a worker node joins or leaves the cluster. More...
 
virtual void remove_worker_node_callback (IWorker_node_callback *callback)=0
 Removes a previously added callback for joined or left worker nodes. More...
 
virtual void add_client_node_callback (IClient_node_callback *callback)=0
 Adds a callback to be called when a client joins or leaves the cluster. More...
 
virtual void remove_client_node_callback (IClient_node_callback *callback)=0
 Removes a previously added callback for joined or left client nodes. More...
 
virtual void add_head_node_callback (IHead_node_callback *callback)=0
 Adds a callback to be called when a new node becomes head node. More...
 
virtual void remove_head_node_callback (IHead_node_callback *callback)=0
 Removes a previously added callback for notification about a new head node. More...
 
virtual const IWorker_node_descriptorgrow ()=0
 Grows the cluster by one node, if a worker node is available. More...
 
virtual Sint32 shrink (const IWorker_node_descriptor *remove_node)=0
 Shrinks the cluster by one node. More...
 
- Public Member Functions inherited from mi::base::IInterface
virtual Uint32 retain () const =0
 Increments the reference count. More...
 
virtual Uint32 release () const =0
 Decrements the reference count. More...
 
virtual const IInterfaceget_interface (const Uuid &interface_id) const =0
 Acquires a const interface from another. More...
 
template<class T>
const T * get_interface () const
 Acquires a const interface from another. More...
 
virtual IInterfaceget_interface (const Uuid &interface_id)=0
 Acquires a mutable interface from another. More...
 
template<class T>
T * get_interface ()
 Acquires a mutable interface from another. More...
 
virtual Uuid get_iid () const =0
 Returns the interface ID of the most derived interface. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from mi::base::Interface_declare< 0x0a58b727, ... >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 
- Static Public Member Functions inherited from mi::base::IInterface
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface. More...
 

Detailed Description

The interface to a cluster created and managed by the node manager.

As long as an application holds this interface, the application will be part of the cluster. Releasing the last handle to this interface gives up cluster membership. When that happens, the node manager will check if there are no more clients. If there are still clients, the cluster will be kept alive. If there are none, then the optional timeout will be started. After the timeout elapsed without another client joining, or immediately if there is no timeout, the cluster will be shut down.

Member Enumeration Documentation

 Cluster_status

Possible cluster states.

See also
get_cluster_status().
Enumerator
CLUSTER_ESTABLISHED 

The cluster has been successfully established.

CLUSTER_SHUTDOWN 

The cluster has been shutdown.

CLUSTER_FAILURE 

The cluster has failed for unspecified reasons.

Member Function Documentation

 add_client_node_callback()

virtual void mi::neuraylib::INode_manager_cluster::add_client_node_callback ( IClient_node_callback callback)
pure virtual

Adds a callback to be called when a client joins or leaves the cluster.

Note that when adding a callback, it will be called automatically for all client nodes already in the cluster.

Parameters
callbackThe callback to be added.
See also
remove_client_node_callback()

 add_cluster_property_callback()

virtual void mi::neuraylib::INode_manager_cluster::add_cluster_property_callback ( ICluster_property_callback callback)
pure virtual

Adds a callback to be called when a cluster property changes.

When adding a callback it will be called immediately once. The cluster descriptor will contain all cluster properties known at this point.

Parameters
callbackThe callback to be added.
See also
remove_cluster_property_callback()

 add_head_node_callback()

virtual void mi::neuraylib::INode_manager_cluster::add_head_node_callback ( IHead_node_callback callback)
pure virtual

Adds a callback to be called when a new node becomes head node.

When adding a callback, it will be called immediately once.

Parameters
callbackThe callback to be added.
See also
remove_client_node_callback()

 add_worker_node_callback()

virtual void mi::neuraylib::INode_manager_cluster::add_worker_node_callback ( IWorker_node_callback callback)
pure virtual

Adds a callback to be called when a worker node joins or leaves the cluster.

Note that when adding a callback, it will be called automatically for all worker nodes already in the cluster.

Parameters
callbackThe callback to be added.
See also
remove_worker_node_callback()

 add_worker_property_callback()

virtual void mi::neuraylib::INode_manager_cluster::add_worker_property_callback ( IWorker_node_property_callback callback)
pure virtual

Adds a callback to be called when a property of a worker node changes.

When adding a callback it will be called immediately once for all worker nodes existing at this point. The descriptor contains all properties for the worker node known at this point.

Parameters
callbackThe callback to be added.
See also
remove_worker_property_callback()

 get_cluster_descriptor()

virtual const ICluster_descriptor * mi::neuraylib::INode_manager_cluster::get_cluster_descriptor ( ) const
pure virtual

Returns the cluster descriptor for the cluster.

 get_cluster_status()

virtual Cluster_status mi::neuraylib::INode_manager_cluster::get_cluster_status ( ) const
pure virtual

Returns the status of the cluster.

 get_head_node()

virtual IWorker_node_descriptor * mi::neuraylib::INode_manager_cluster::get_head_node ( )
pure virtual

Returns the head node.

The head node is a cluster member flagged by the node manager for applications that need support for a head node. It can be referenced by a placeholder substring in the argument string passed to mi::neuraylib::INode_manager_client::join_or_create_cluster().

See also
mi::neuraylib::INode_manager_client::join_or_create_cluster() for how to reference the head node in the argument string.
Returns
The descriptor for the head node, or NULL if no head node has been flagged.

 grow()

virtual const IWorker_node_descriptor * mi::neuraylib::INode_manager_cluster::grow ( )
pure virtual

Grows the cluster by one node, if a worker node is available.

The new node will be added to the cluster by starting a worker process on that node using the worker_node_filter, program_name, argument_string and child_process_timeout parameters passed to mi::neuraylib;;INode_manager_client::join_or_create_cluster() to create the cluster.

Returns
The descriptor of the worker node that has been added to the cluster or NULL if no worker node was available.

 remove_client_node_callback()

virtual void mi::neuraylib::INode_manager_cluster::remove_client_node_callback ( IClient_node_callback callback)
pure virtual

Removes a previously added callback for joined or left client nodes.

Parameters
callbackThe callback to be removed.
See also
add_client_node_callback()

 remove_cluster_property()

virtual Sint32 mi::neuraylib::INode_manager_cluster::remove_cluster_property ( const char *  name)
pure virtual

Removes a cluster property.

This change will be forwarded immediately to all clients.

See also
set_cluster_property() to set cluster properties, get_cluster_descriptor() and mi::neuraylib::ICluster_descriptor to retrieve cluster properties
Parameters
nameThe name of the property to remove.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: There is no property with the given name.

 remove_cluster_property_callback()

virtual void mi::neuraylib::INode_manager_cluster::remove_cluster_property_callback ( ICluster_property_callback callback)
pure virtual

Removes a previously added callback for cluster property changes.

Parameters
callbackThe callback to be removed.
See also
add_cluster_property_callback()

 remove_head_node_callback()

virtual void mi::neuraylib::INode_manager_cluster::remove_head_node_callback ( IHead_node_callback callback)
pure virtual

Removes a previously added callback for notification about a new head node.

Parameters
callbackThe callback to be removed.
See also
add_client_node_callback()

 remove_worker_node_callback()

virtual void mi::neuraylib::INode_manager_cluster::remove_worker_node_callback ( IWorker_node_callback callback)
pure virtual

Removes a previously added callback for joined or left worker nodes.

Parameters
callbackThe callback to be removed.
See also
add_worker_node_callback()

 remove_worker_property_callback()

virtual void mi::neuraylib::INode_manager_cluster::remove_worker_property_callback ( IWorker_node_property_callback callback)
pure virtual

Removes a previously added callback for property changes of worker nodes.

Parameters
callbackThe callback to be removed.
See also
add_worker_property_callback()

 restart_worker_program()

virtual Sint32 mi::neuraylib::INode_manager_cluster::restart_worker_program ( )
pure virtual

Restarts the program that is supposed to run on all workers.

The program command line used will be the same that was passed to mi::neuraylib::INode_manager_client::join_or_create_cluster() when the cluster was created.

Returns
  • 0: Success.
  • -1: An error occurred while restarting.

 set_cluster_property()

virtual Sint32 mi::neuraylib::INode_manager_cluster::set_cluster_property ( const char *  name,
const char *  value 
)
pure virtual

Sets a cluster property.

This change will be forwarded immediately to all clients.

See also
remove_cluster_property() to remove cluster properties, get_cluster_descriptor() and mi::neuraylib::ICluster_descriptor to retrieve cluster properties
Parameters
nameThe name of the property to set.
valueThe value string to be set for the property.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointers).

 set_timeout()

virtual void mi::neuraylib::INode_manager_cluster::set_timeout ( Float64  timeout)
pure virtual

Sets the keep-alive timeout for the cluster.

The keep-alive timeout specifies the amount of time (in seconds) the cluster will remain operational after the last client left the cluster. If no timeout is set, the value defaults to 0, meaning the cluster will be shut down as soon as the last connected client disconnects.

See also
mi::neuraylib::ICluster_descriptor::get_timeout()

 shrink()

virtual Sint32 mi::neuraylib::INode_manager_cluster::shrink ( const IWorker_node_descriptor remove_node)
pure virtual

Shrinks the cluster by one node.

Parameters
remove_nodeThe descriptor of the node that is supposed to be removed from the cluster.
Returns
- 0 Success.
  • -1 The specified node is not a member of the cluster.
  • -2 The specified node is invalid (NULL pointer).

 shutdown()

virtual void mi::neuraylib::INode_manager_cluster::shutdown ( )
pure virtual

Initiates the shutdown of the cluster.

This method shuts down the cluster unconditionally, independent of the keep-alive timeout or the number of client nodes using the cluster.

 shutdown_worker_program()

virtual Sint32 mi::neuraylib::INode_manager_cluster::shutdown_worker_program ( )
pure virtual

Shuts down the program that was started on all worker nodes when the cluster was created.

The cluster with all worker nodes is retained. This call will usually be followed by a call to restart_worker_program().

Returns
  • 0: Success.
  • -1: An error occurred while shutting down.

 start_worker_program()

virtual Sint32 mi::neuraylib::INode_manager_cluster::start_worker_program ( const char *  program_name,
const char *  argument_string,
Uint32  child_process_timeout = 0 
)
pure virtual

Starts a worker program if none has been started when the cluster has been created.

The method is to be used if program_name in mi::neuraylib::INode_manager_client::join_or_create_cluster() was NULL.

Parameters
program_nameThe name of the program to run on the worker nodes. If NULL, a cluster is created without child processes being forked by the worker nodes.
argument_stringArguments to program_name. The string may include the substring %m which will be replaced by the multicast address of the cluster (use %% to escape percent signs). It may also contain the substring %h which will be expanded into the head node, a node marked within the cluster for applications that need support for it. The%H substring will be expanded to 1 on the head node, to 0 on all other hosts. The %n substring will be expanded to the number of nodes in the cluster. If the child_process_timeout parameter is defined, the command line also needs to contain the substrings %w, which will be substituted with the name of the named pipe and %t which will be replaced with the timeout value. If a substring of the format %p:property is included, it will be expanded to the value for the property set by the worker. Please note that adding %p placeholders dismisses nodes during recruitment that do not have the assigned property set.
child_process_timeoutA parameter indicating whether there should be a watchdog controlling the child process on worker nodes. The value specifies the timeout in seconds after which the node manager assumes the child process is hanging. It needs to be >= 5 seconds. This parameter only has an effect when creating new clusters. If it is defined, the argument_string parameter needs to contain the substrings %w and %t.
Returns
0 in case of success, -1 if no cluster has been created, -2 if the worker program can not be started because the cluster is not flagged 'reusable' and -3 if no program name was specified.