neuray API Programmer's Manual

mi::neuraylib::INetwork_configuration Class Reference

[Configuration Interfaces]

Description

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

Public Enumerations

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 Member Functions

virtual Sint32 add_configured_host( const char* address) =0
Adds a host to the list of hosts to connect to. More...
virtual const IStringget_cluster_interface() const =0
Returns the chosen cluster interface address. More...
virtual Sint32 get_compression_level() const =0
Returns the compression level for network traffic. More...
virtual const IStringget_configured_host( Uint32 index) const =0
Returns the address of a host from the list of configured hosts. More...
virtual const IStringget_discovery_address() const =0
Returns the discovery address. More...
virtual const IStringget_discovery_identifier() const =0
Returns the discovery identifier. More...
virtual Mode get_mode() const =0
Returns the configured networking mode. More...
virtual const IStringget_multicast_address() const =0
Returns the base multicast address. More...
virtual Uint32 get_multicast_ttl() const =0
Returns the set multicast TTL/hop value. More...
virtual const INetwork_statisticsget_network_statistics() const =0
Returns an interface to inquire network statistics. More...
virtual Uint32 get_number_of_configured_hosts() const =0
Returns the current number of configured hosts. More...
virtual const IStringget_rdma_interface() const =0
Returns RDMA InfiniBand interface to be used. More...
virtual Uint32 get_redundancy_level() const =0
Returns the redundancy level. More...
virtual Status get_status() const =0
Returns the status of the networking connection.
virtual bool  get_use_rdma() const =0
Indicates whether RDMA InfiniBand is enabled. More...
virtual Sint32 register_host_callback( IHost_callback* callback) =0
Registers a callback for cluster changes. More...
virtual Sint32 remove_configured_host( const char* address) =0
Removes a host from the list of hosts to connect to. More...
virtual Sint32 set_cluster_interface( const char* address) =0
Sets the interface to be used for outgoing packets. More...
virtual Sint32 set_compression_level( Uint32 level) =0
Sets the compression level for network traffic. More...
virtual Sint32 set_discovery_address( const char* address) =0
Sets the discovery address to be used for automatic host discovery. More...
virtual Sint32 set_discovery_identifier( const char* identifier) =0
Sets the discovery identifier. More...
virtual Sint32 set_mode( Mode mode) =0
Sets the networking mode. More...
virtual Sint32 set_multicast_address( const char* address) =0
Sets the base multicast address to be used for networking. More...
virtual void set_multicast_ttl( Uint32 ttl) =0
Sets the time to live (TTL/hops) of multicast packets. More...
virtual Sint32 set_rdma_interface( const char* rdma_interface) =0
Set the RDMA InfiniBand interface to be used. More...
virtual Sint32 set_redundancy_level( Uint32 level) =0
Sets the redundancy level to be used for storing objects in the database. More...
virtual Sint32 set_use_rdma( bool use_rdma) =0
Enables or disables the usage of RDMA InfiniBand. More...
virtual Sint32 unregister_host_callback( IHost_callback* callback) =0
Unregisters a callback for cluster changes. More...

Enums

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 = 0
Networking is switched off.
MODE_TCP = 1
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 = 2
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 = 3
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.
MODE_FORCE_32_BIT = 0xffffffffU
enum mi::​neuraylib::​INetwork_configuration::Status

The different states for the networking connection.

See also:

get_status()

Enumerator:

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

Member Functions

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.

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.

virtual Sint32 mi::​neuraylib::​INetwork_configuration::get_compression_level() const [pure virtual]

Returns the compression level for network traffic.

See also:

set_compression_level()

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.

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.

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.

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 has been started.

See also:

set_mode()

Returns

The configured networking mode.

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.

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.

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.

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

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.

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.

virtual Status mi::​neuraylib::​INetwork_configuration::get_status() const [pure virtual]

Returns the status of the networking connection.

virtual bool mi::​neuraylib::​INetwork_configuration::get_use_rdma() const [pure virtual]

Indicates whether RDMA InfiniBand is enabled.

See also:

set_use_rdma()

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

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.

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://". 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 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.

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

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

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 has been started.

See also:

get_discovery_identifier()

Parameters

identifier
The discovery identifier.

Returns

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

virtual Sint32 mi::​neuraylib::​INetwork_configuration::set_mode( Mode mode) [pure virtual]

Sets the networking mode. This can only be called before has been started.

See also:

get_mode()

Parameters

mode
The desired networking mode.

Returns

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

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

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 has been started.

See also:

get_multicast_ttl()

Parameters

ttl
The new TTL/hop value.
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 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.

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 has been started.

See also:

get_redundancy_level()

Note:

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

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.

Returns

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

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.

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.