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

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 IStringget_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 IStringget_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 IStringget_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 IStringget_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 IStringget_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_statisticsget_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 IStringget_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 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< 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

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

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
addressThe 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
indexThe 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
callbackThe 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
addressThe 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
addressThe 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
levelThe 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
addressThe 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
identifierThe 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
modeThe 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
addressThe 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
ttlThe 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_interfaceThe 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
levelThe 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_rdmaIndicates 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
callbackThe callback to be unregistered.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: callback is not a registered callback.