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_descriptor *	get_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_descriptor *	get_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_descriptor *	grow ()=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 IInterface *	get_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 IInterface *	get_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

enum mi::neuraylib::INode_manager_cluster::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

callback The 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

callback The 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

callback The 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

callback The 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

callback The 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

callback The 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

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.

^◆ 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

callback The 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

callback The 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

callback The 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

callback The 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

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).

^◆ 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_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).

^◆ 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_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.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Cluster_status

Member Function Documentation

◆ add_client_node_callback()

◆ add_cluster_property_callback()

◆ add_head_node_callback()

◆ add_worker_node_callback()

◆ add_worker_property_callback()

◆ get_cluster_descriptor()

◆ get_cluster_status()

◆ get_head_node()

◆ grow()

◆ remove_client_node_callback()

◆ remove_cluster_property()

◆ remove_cluster_property_callback()

◆ remove_head_node_callback()

◆ remove_worker_node_callback()

◆ remove_worker_property_callback()

◆ restart_worker_program()

◆ set_cluster_property()

◆ set_timeout()

◆ shrink()

◆ shutdown()

◆ shutdown_worker_program()

◆ start_worker_program()

^◆ Cluster_status

^◆ add_client_node_callback()

^◆ add_cluster_property_callback()

^◆ add_head_node_callback()

^◆ add_worker_node_callback()

^◆ add_worker_property_callback()

^◆ get_cluster_descriptor()

^◆ get_cluster_status()

^◆ get_head_node()

^◆ grow()

^◆ remove_client_node_callback()

^◆ remove_cluster_property()

^◆ remove_cluster_property_callback()

^◆ remove_head_node_callback()

^◆ remove_worker_node_callback()

^◆ remove_worker_property_callback()

^◆ restart_worker_program()

^◆ set_cluster_property()

^◆ set_timeout()

^◆ shrink()

^◆ shutdown()

^◆ shutdown_worker_program()

^◆ start_worker_program()