mi::neuraylib::INode_manager_cluster Class Reference
[Node manager]
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.
Public Enumerations
- enum Cluster_status{ CLUSTER_ESTABLISHED = 0, CLUSTER_SHUTDOWN = 1, CLUSTER_FAILURE = 2, CLUSTER_FORCE_32_BIT = 0xffffffffU}
- Possible cluster states. More...
Public Member Functions
- 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 add_cluster_property_callback( ICluster_property_callback* callback) =0
- Adds a callback to be called when a cluster property changes. 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 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 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 const ICluster_descriptor* get_cluster_descriptor() const =0
- Returns the cluster descriptor for the cluster.
- virtual Cluster_status get_cluster_status() const =0
- Returns the status of the cluster.
- virtual IWorker_node_descriptor* get_head_node() =0
- Returns the head node. More...
- virtual const IWorker_node_descriptor* grow() =0
- Grows the cluster by one node, if a worker node is available. 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 Sint32 remove_cluster_property( const char* name) =0
- Removes a cluster property. More...
- virtual void remove_cluster_property_callback( ICluster_property_callback* callback) =0
- Removes a previously added callback for cluster property changes. 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 void remove_worker_node_callback( IWorker_node_callback* callback) =0
- Removes a previously added callback for joined or left worker nodes. 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 Sint32 restart_worker_program() =0
- Restarts the program that is supposed to run on all workers. More...
- virtual Sint32 set_cluster_property( const char* name, const char* value) =0
- Sets a cluster property. More...
- virtual void set_timeout( Float64 timeout) =0
- Sets the keep-alive timeout for the cluster. More...
- virtual Sint32 shrink( const IWorker_node_descriptor* remove_node) =0
- Shrinks the cluster by one node. More...
- virtual void shutdown() =0
- Initiates the shutdown of the cluster. 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 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...
Enums
- enum mi::neuraylib::INode_manager_cluster::Cluster_status
Member Functions
- 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.
See also:
Parameters
- callback
- The callback to be added.
- 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.
See also:
remove_cluster_property_callback()
Parameters
- callback
- The callback to be added.
- 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.
See also:
Parameters
- callback
- The callback to be added.
- 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.
See also:
Parameters
- callback
- The callback to be added.
- 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.
See also:
remove_worker_property_callback()
Parameters
- callback
- The callback to be added.
- virtual const ICluster_descriptor* mi::neuraylib::INode_manager_cluster::get_cluster_descriptor() const [pure virtual]
-
Returns the cluster descriptor for the cluster.
- virtual Cluster_status mi::neuraylib::INode_manager_cluster::get_cluster_status() const [pure virtual]
-
Returns the status of the cluster.
- 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.
- 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.
- 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.
See also:
Parameters
- callback
- The callback to be removed.
- 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
- name
- The name of the property to remove.
Returns
- 0: Success.
- -1: Invalid parameters (NULL pointer).
- -2: There is no property with the given name.
- 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.
See also:
add_cluster_property_callback()
Parameters
- callback
- The callback to be removed.
- 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.
See also:
Parameters
- callback
- The callback to be removed.
- 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.
See also:
Parameters
- callback
- The callback to be removed.
- 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.
See also:
add_worker_property_callback()
Parameters
- callback
- The callback to be removed.
- 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.
- 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
- name
- The name of the property to set.
- value
- The value string to be set for the property.
Returns
- 0: Success.
- -1: Invalid parameters (NULL pointers).
- 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()
- virtual Sint32 mi::neuraylib::INode_manager_cluster::shrink( const IWorker_node_descriptor* remove_node) [pure virtual]
-
Shrinks the cluster by one node.
Parameters
- remove_node
- The 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).
- 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.
- 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.
- 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_name
- The 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_string
- Arguments 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_timeout
- A 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.