This interface is used to query and change the networking configuration. More...

#include <inetwork_configuration.h>

Inheritance diagram for mi::neuraylib::INetwork_configuration:

Public Types
enum	Mode { MODE_OFF = 0 , MODE_TCP = 1 , MODE_UDP = 2 , MODE_TCP_WITH_DISCOVERY = 3 , MODE_FORCE_32_BIT = 0xffffffffU }
	Constants for the networking mode. More...

enum	Status { CONNECTION_STANDALONE = 0 , CONNECTION_STARTING = 1 , CONNECTION_ESTABLISHED = 2 , CONNECTION_SHUTTINGDOWN = 3 , CONNECTION_SHUTDOWN = 4 , CONNECTION_FAILURE = 5 , CONNECTION_FORCE_32_BIT = 0xffffffffU }
	The different states for the networking connection. More...

Public Types inherited from mi::base::Interface_declare< 0xb60d3124, ... >
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 Sint32	set_mode (Mode mode)=0
	Sets the networking mode. More...

virtual Mode	get_mode () const =0
	Returns the configured networking mode. More...

virtual Status	get_status () const =0
	Returns the status of the networking connection. More...

virtual Sint32	set_multicast_address (const char *address)=0
	Sets the base multicast address to be used for networking. More...

virtual const IString *	get_multicast_address () const =0
	Returns the base multicast address. More...

virtual void	set_multicast_ttl (Uint32 ttl)=0
	Sets the time to live (TTL/hops) of multicast packets. More...

virtual Uint32	get_multicast_ttl () const =0
	Returns the set multicast TTL/hop value. More...

virtual Sint32	set_cluster_interface (const char *address)=0
	Sets the interface to be used for outgoing packets. More...

virtual const IString *	get_cluster_interface () const =0
	Returns the chosen cluster interface address. More...

virtual Sint32	set_discovery_address (const char *address)=0
	Sets the discovery address to be used for automatic host discovery. More...

virtual const IString *	get_discovery_address () const =0
	Returns the discovery address. More...

virtual Sint32	set_discovery_identifier (const char *identifier)=0
	Sets the discovery identifier. More...

virtual const IString *	get_discovery_identifier () const =0
	Returns the discovery identifier. More...

virtual Sint32	set_redundancy_level (Uint32 level)=0
	Sets the redundancy level to be used for storing objects in the database. More...

virtual Uint32	get_redundancy_level () const =0
	Returns the redundancy level. More...

virtual Sint32	add_configured_host (const char *address)=0
	Adds a host to the list of hosts to connect to. More...

virtual Sint32	remove_configured_host (const char *address)=0
	Removes a host from the list of hosts to connect to. More...

virtual Uint32	get_number_of_configured_hosts () const =0
	Returns the current number of configured hosts. More...

virtual const IString *	get_configured_host (Uint32 index) const =0
	Returns the address of a host from the list of configured hosts. More...

virtual Sint32	set_compression_level (Uint32 level)=0
	Sets the compression level for network traffic. More...

virtual Sint32	get_compression_level () const =0
	Returns the compression level for network traffic. More...

virtual Sint32	register_host_callback (IHost_callback *callback)=0
	Registers a callback for cluster changes. More...

virtual Sint32	unregister_host_callback (IHost_callback *callback)=0
	Unregisters a callback for cluster changes. More...

virtual const INetwork_statistics *	get_network_statistics () const =0
	Returns an interface to inquire network statistics. More...

virtual Sint32	set_use_rdma (bool use_rdma)=0
	Enables or disables the usage of RDMA InfiniBand. More...

virtual bool	get_use_rdma () const =0
	Indicates whether RDMA InfiniBand is enabled. More...

virtual Sint32	set_rdma_interface (const char *rdma_interface)=0
	Set the RDMA InfiniBand interface to be used. More...

virtual const IString *	get_rdma_interface () const =0
	Returns RDMA InfiniBand interface to be used. 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< 0xb60d3124, ... >
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

This interface is used to query and change the networking configuration.

Member Enumeration Documentation

^◆ Mode

enum mi::neuraylib::INetwork_configuration::Mode

Constants for the networking mode.

Each setting represents the method of finding other hosts and whether they communicate over unicast, multicast, or a combination of both after establishing a cluster.

See also: set_mode(), get_mode()

Enumerator
MODE_OFF	Networking is switched off.
MODE_TCP	Networking is using TCP/IP connections between hosts. Only hosts configured in the host list can join the network. If a host is not available at startup no further connection attempts will be made.
MODE_UDP	Networking is switched to UDP mode with multicast. Hosts can join dynamically after being started without being listed in the configuration. Data transmission is done using high bandwidth unicast and multicast UDP. The multicast address is configured using set_multicast_address().
MODE_TCP_WITH_DISCOVERY	Networking is using TCP/IP connections between hosts. Hosts can join dynamically after being started without being listed in the configuration. The method set_discovery_address() controls which address to use for finding other hosts.

^◆ Status

enum mi::neuraylib::INetwork_configuration::Status

The different states for the networking connection.

See also: get_status()

Enumerator
CONNECTION_STANDALONE	Networking is not enabled (see set_mode()) or is not available, e.g., due to license restrictions.
CONNECTION_STARTING	DiCE is in the process of starting up.
CONNECTION_ESTABLISHED	All connections are established as configured.
CONNECTION_SHUTTINGDOWN	DiCE is in the process of shutting down.
CONNECTION_SHUTDOWN	DiCE has shut down.
CONNECTION_FAILURE	Networking has failed for some reason.

Member Function Documentation

^◆ add_configured_host()

virtual Sint32 mi::neuraylib::INetwork_configuration::add_configured_host ( const char * address )

pure virtual

Adds a host to the list of hosts to connect to.

This is used in the unicast network modes to specify the hosts to connect to. Note that discovery mode will be disabled if the host list is populated.

See also: remove_configured_host(), get_number_of_configured_hosts(), get_configured_host()

Parameters

address The address of the host.

Returns: 0, in case of success, -1 in case of failure.

^◆ get_cluster_interface()

virtual const IString * mi::neuraylib::INetwork_configuration::get_cluster_interface ( ) const

pure virtual

Returns the chosen cluster interface address.

See also: set_cluster_interface()

Returns: A numerical representation of the cluster interface address and port.

^◆ get_compression_level()

virtual Sint32 mi::neuraylib::INetwork_configuration::get_compression_level ( ) const

pure virtual

Returns the compression level for network traffic.

See also: set_compression_level()

^◆ get_configured_host()

virtual const IString * mi::neuraylib::INetwork_configuration::get_configured_host ( Uint32 index ) const

pure virtual

Returns the address of a host from the list of configured hosts.

See also: add_configured_host(), remove_configured_host(), get_number_of_configured_hosts()

Parameters

index The index of the host to be returned.

Returns: The address of the host, or NULL in case of invalid indices.

^◆ get_discovery_address()

virtual const IString * mi::neuraylib::INetwork_configuration::get_discovery_address ( ) const

pure virtual

Returns the discovery address.

See also: set_discovery_address()

Returns: A numerical representation of the discovery address and port.

^◆ get_discovery_identifier()

virtual const IString * mi::neuraylib::INetwork_configuration::get_discovery_identifier ( ) const

pure virtual

Returns the discovery identifier.

See also: set_discovery_identifier()

Returns: The discovery identifier.

^◆ get_mode()

virtual Mode mi::neuraylib::INetwork_configuration::get_mode ( ) const

pure virtual

Returns the configured networking mode.

Note that networking might not be used even though it was configured, e.g., due to license restrictions. Make sure to check whether get_status() returns CONNECTION_STANDALONE or CONNECTION_ESTABLISHED after DiCE has been started.

See also: set_mode()

Returns: The configured networking mode.

^◆ get_multicast_address()

virtual const IString * mi::neuraylib::INetwork_configuration::get_multicast_address ( ) const

pure virtual

Returns the base multicast address.

See also: set_multicast_address()

Returns: A numerical representation of the base multicast address and port.

^◆ get_multicast_ttl()

virtual Uint32 mi::neuraylib::INetwork_configuration::get_multicast_ttl ( ) const

pure virtual

Returns the set multicast TTL/hop value.

See also: set_multicast_ttl()

Returns: The current TTL/hop value.

^◆ get_network_statistics()

virtual const INetwork_statistics * mi::neuraylib::INetwork_configuration::get_network_statistics ( ) const

pure virtual

Returns an interface to inquire network statistics.

Returns: The network statistics object.

^◆ get_number_of_configured_hosts()

virtual Uint32 mi::neuraylib::INetwork_configuration::get_number_of_configured_hosts ( ) const

pure virtual

Returns the current number of configured hosts.

See also: add_configured_host(), remove_configured_host(), get_configured_host()

^◆ get_rdma_interface()

virtual const IString * mi::neuraylib::INetwork_configuration::get_rdma_interface ( ) const

pure virtual

Returns RDMA InfiniBand interface to be used.

See also: get_rdma_interface()

Returns: The RDMA interface to be used, or NULL if none is found.

^◆ get_redundancy_level()

virtual Uint32 mi::neuraylib::INetwork_configuration::get_redundancy_level ( ) const

pure virtual

Returns the redundancy level.

See also: set_redundancy_level()

Returns: The configured redundancy level.

^◆ get_status()

virtual Status mi::neuraylib::INetwork_configuration::get_status ( ) const

pure virtual

Returns the status of the networking connection.

^◆ get_use_rdma()

virtual bool mi::neuraylib::INetwork_configuration::get_use_rdma ( ) const

pure virtual

Indicates whether RDMA InfiniBand is enabled.

See also: set_use_rdma()

^◆ register_host_callback()

virtual Sint32 mi::neuraylib::INetwork_configuration::register_host_callback ( IHost_callback * callback )

pure virtual

Registers a callback for cluster changes.

For example, this callback can be used to get notifications whenever a host joins or leaves the cluster, or when its properties change.

See also: unregister_host_callback()

Parameters

callback The callback to be registered.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

^◆ remove_configured_host()

virtual Sint32 mi::neuraylib::INetwork_configuration::remove_configured_host ( const char * address )

pure virtual

Removes a host from the list of hosts to connect to.

This is used in the unicast network modes to specify the hosts to connect to.

See also: add_configured_host(), get_number_of_configured_hosts(), get_configured_host()

Parameters

address The address of the host.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_cluster_interface()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_cluster_interface ( const char * address )

pure virtual

Sets the interface to be used for outgoing packets.

If not set, it will be the "any" address. The string may end with : and a port number to select which port to listen to for UDP and TCP unicast. If no port is set and unicast only mode is set, port 10000 will be used.

The IP address of the interface can also be specified as a sub net using the CIDR notation a.b.c.d/xx. If there is an interface on the host with an address inside this range the first match will be used. This is useful for example when configuring several hosts. This means that on a host which has the address 192.168.1.1, specifying the address as 192.168.0.0/16:10000 would make the host bind to the 192.168.1.1 address on port 10000.

IPv6 addresses need to be surrounded by brackets but can otherwise be used just like their IPv4 counterparts mentioned above. The address [::] means the "any IPv6 interface" address.

It is also possible to specify an interface name instead of an address. The name must be prefixed by the string "if://". DiCE will then take the address from the interface. A single "*" wildcard may be used at the end of the requested name, in which case the first matching interface will be selected.

This can only be configured before DiCE has been started.

See also: get_cluster_interface()

Parameters

address The interface address and port.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_compression_level()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_compression_level ( Uint32 level )

pure virtual

Sets the compression level for network traffic.

This can only be configured before DiCE has been started.

See also: get_compression_level()

Parameters

level The desired compression level. Valid values are 0 to 9. The value 0 disables compression. The higher the value, the higher the efforts to compress network traffic and the smaller the amount of data transferred across the network.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_discovery_address()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_discovery_address ( const char * address )

pure virtual

Sets the discovery address to be used for automatic host discovery.

If it is a multicast address multicast will be used to find the other hosts. If it is a unicast address the discovery network assumes that it is the address of the master node which has the list of all other hosts. If that unicast address is the same as the address of the running host, the discovery network will consider itself the master.

An IPv4 UDP multicast address is specified by an address in the range 224.0.0.0 to 239.255.255.255, inclusive, along with a port. An IPv6 multicast address is specified by an IPv6 address with a high-order byte ff. This will be used when MODE_TCP_WITH_DISCOVERY is set. It must include a port, like ip:port. There is a default address which will be used if none is set, both for IPv4 and IPv6.

This can only be configured before DiCE has been started.

Note that discovery mode will be disabled if any hosts are added using the add_configured_hosts method.

See also: get_discovery_address()

Parameters

address The discovery address and port.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_discovery_identifier()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_discovery_identifier ( const char * identifier )

pure virtual

Sets the discovery identifier.

The discovery identifier restricts the cluster to hosts that use the same identifier. This can be used to make sure that only compatible or selected nodes can join the cluster. In particular, if several clusters exist this identifier can be used to ensure that the host does not by accident join the wrong cluster. There is a default identifier which will be used if none is set.

Note: This is an additional check on top of the discovery, it is not an alternative to for example using different multicast addresses for different clusters. If two hosts with
different identifiers see each other through the discovery mechanisms then an error will be issued and the hosts will not be able to join a cluster.

This can only be configured before DiCE has been started.

See also: get_discovery_identifier()

Parameters

identifier The discovery identifier.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_mode()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_mode ( Mode mode )

pure virtual

Sets the networking mode.

This can only be called before DiCE has been started.

See also: get_mode()

Parameters

mode	The desired networking mode.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_multicast_address()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_multicast_address ( const char * address )

pure virtual

Sets the base multicast address to be used for networking.

This address will be used for UDP mode networking. An IPv4 UDP multicast address is specified by an address in the range 224.0.0.0 to 239.255.255.255, inclusive, along with a port. An IPv6 multicast address is specified by an IPv6 address with a high-order byte ff.

Note that actually not just one, but several multicast addresses are used. The other multicast addresses are obtained by incrementing the last octet. Hence, the value configured here is called the base multicast address.

This can only be configured before DiCE has been started.

See also: get_multicast_address()

Parameters

address The base multicast address and port.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_multicast_ttl()

virtual void mi::neuraylib::INetwork_configuration::set_multicast_ttl ( Uint32 ttl )

pure virtual

Sets the time to live (TTL/hops) of multicast packets.

The default value is 1.

This can only be configured before DiCE has been started.

See also: get_multicast_ttl()

Parameters

ttl	The new TTL/hop value.

^◆ set_rdma_interface()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_rdma_interface ( const char * rdma_interface )

pure virtual

Set the RDMA InfiniBand interface to be used.

The string can be either the interface name or it's address, which can be expressed in CIDR format as well, similar to set_cluster_interface. Note that only interface names that start with the prefix 'ib' are accepted.

If unspecified, an arbitrary RDMA InfiniBand interface will be chosen.

This can only be configured before DiCE has been started.

See also: get_rdma_interface()

Parameters

rdma_interface The RDMA InfiniBand interface to be used, either "ib0", "ib1", etc. or the address of an InfiniBand interface.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_redundancy_level()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_redundancy_level ( Uint32 level )

pure virtual

Sets the redundancy level to be used for storing objects in the database.

This can only be configured before DiCE has been started.

See also: get_redundancy_level()

Parameters

level The redundancy level. This is limited to a compiled in maximum that is currently set to 4. If the given value exceeds the possible maximum the return value will signal an error but the value will be set to the possible maximum.

Note: This value must be set to the same value on all hosts.

Returns: 0, in case of success, -1 in case of failure.

^◆ set_use_rdma()

virtual Sint32 mi::neuraylib::INetwork_configuration::set_use_rdma ( bool use_rdma )

pure virtual

Enables or disables the usage of RDMA InfiniBand.

The default value is false (disabled).

See also: get_use_rdma()

Parameters

use_rdma Indicates whether RDMA InfiniBand should be used (if it is available).

Returns: 0, in case of success, -1 in case of failure.

^◆ unregister_host_callback()

virtual Sint32 mi::neuraylib::INetwork_configuration::unregister_host_callback ( IHost_callback * callback )

pure virtual

Unregisters a callback for cluster changes.

See also: register_host_callback()

Parameters

callback The callback to be unregistered.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).
-2: callback is not a registered callback.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Mode

◆ Status

Member Function Documentation

◆ add_configured_host()

◆ get_cluster_interface()

◆ get_compression_level()

◆ get_configured_host()

◆ get_discovery_address()

◆ get_discovery_identifier()

◆ get_mode()

◆ get_multicast_address()

◆ get_multicast_ttl()

◆ get_network_statistics()

◆ get_number_of_configured_hosts()

◆ get_rdma_interface()

◆ get_redundancy_level()

◆ get_status()

◆ get_use_rdma()

◆ register_host_callback()

◆ remove_configured_host()

◆ set_cluster_interface()

◆ set_compression_level()

◆ set_discovery_address()

◆ set_discovery_identifier()

◆ set_mode()

◆ set_multicast_address()

◆ set_multicast_ttl()

◆ set_rdma_interface()

◆ set_redundancy_level()

◆ set_use_rdma()

◆ unregister_host_callback()

^◆ Mode

^◆ Status

^◆ add_configured_host()

^◆ get_cluster_interface()

^◆ get_compression_level()

^◆ get_configured_host()

^◆ get_discovery_address()

^◆ get_discovery_identifier()

^◆ get_mode()

^◆ get_multicast_address()

^◆ get_multicast_ttl()

^◆ get_network_statistics()

^◆ get_number_of_configured_hosts()

^◆ get_rdma_interface()

^◆ get_redundancy_level()

^◆ get_status()

^◆ get_use_rdma()

^◆ register_host_callback()

^◆ remove_configured_host()

^◆ set_cluster_interface()

^◆ set_compression_level()

^◆ set_discovery_address()

^◆ set_discovery_identifier()

^◆ set_mode()

^◆ set_multicast_address()

^◆ set_multicast_ttl()

^◆ set_rdma_interface()

^◆ set_redundancy_level()

^◆ set_use_rdma()

^◆ unregister_host_callback()