Skip to content
v1.11dev
GitHub

Reference

Transfer codes and errors

This page lists the return values of the transfer functions, the error codes of fairmq/Error.h, and all exception types of FairMQ. For the handling of these errors, see Handle errors and timeouts.

Transfer codes

Section titled “Transfer codes”

The enum fair::mq::TransferCode is in fairmq/Socket.h. Its underlying type is int.

Code Value Returned when
success 0 Never. A complete transfer returns the number of bytes, which is 0 for an empty message.
error -1 The transfer failed. The transport logs Failed transfer on socket … with the reason. If the transport is terminated, it logs Terminating socket … (severity debug).
timeout -2 The timeout ended before the transfer was possible. With the timeout 0, the transfer was not possible at once.
interrupted -3 The transport is interrupted, because a transition is pending.

These functions return an int64_t with the number of bytes or a negative code:

Function Description
Device::Send(), Device::Receive() Use the timeout of the channel.
Device::Send(…, timeout), Device::Receive(…, timeout) Use the timeout argument.
Channel::Send(), Channel::Receive() Use the timeout argument, if you give one. Otherwise they use the timeout of the channel.
Socket::Send(), Socket::Receive() The virtual functions of the transports. The default timeout is -1.

All functions accept a MessagePtr, a Parts or a std::vector<MessagePtr>. For a multipart message, the number of bytes is the sum of all parts.

Timeout values

Section titled “Timeout values”
Timeout Behavior
Negative, default -1 Wait until the transfer is possible, or until an interruption.
0 Do not wait.
Positive Wait up to this time in ms, rounded up to a multiple of 100 ms.

The channel properties sndTimeoutMs and rcvTimeoutMs give the timeout of a channel. Their default is -1 (Channel.h). The steps of 100 ms come from the internal socket timeout of the zeromq and shmem transports (zeromq/Common.h).

Error codes

Section titled “Error codes”

The enum fair::mq::ErrorCode is in fairmq/Error.h. Its category ErrorCategory has the name fairmq. The messages come from ErrorCategory::message().

Code Value Message Used by
OperationInProgress 10 async operation already in progress Not used in this version.
OperationTimeout 11 async operation timed out Not used in this version.
OperationCanceled 12 async operation canceled Not used in this version.
DeviceChangeStateFailed 13 failed to change state of a fairmq device Device::ChangeStateOrThrow()
DeviceGetPropertiesFailed 14 failed to get fairmq device properties Not used in this version.
DeviceSetPropertiesFailed 15 failed to set fairmq device properties Not used in this version.
Other values — (unrecognized error) —

MakeErrorCode(ErrorCode) returns a std::error_code with the value and the category. ChangeStateOrThrow() throws a std::system_error with this code and the text Invalid transition: <NAME>.

FairMQ exceptions

Section titled “FairMQ exceptions”

All exceptions of FairMQ derive from std::runtime_error, except PluginManager::BadSearchPath. Thus catch (std::exception const&) catches all of them. The namespace is fair::mq.

Device, states and configuration

Section titled “Device, states and configuration”
Exception Header Thrown when
DeviceErrorState States.h A StateQueue gives the state ERROR, for example in Device::WaitForState(). The interactive controller also throws it in ERROR. Text: Controlled device transitioned to error state.
StateMachine::ErrorStateException StateMachine.h RunStateMachine() ends after the transition ErrorFound. Text: Device transitioned to error state.
PropertyNotFoundError ProgOptions.h GetProperty<T>(key) or GetPropertyAsString(key) without a default, for a key that does not exist. Text: Config has no key: <key>.
ParserError JSONParser.h JSONParser(), SuboptParser() or PtreeParser() gets an empty device id. The config plugin does not call the parser without an id.
Channel::ChannelConfigurationError Channel.h Channel::Validate() finds an invalid type, an invalid method, a negative buffer or kernel size, or a negative rateLogging.
PollerError Poller.h A poller gets an unknown channel name (in the constructor, CheckInput() or CheckOutput()), or the poll fails.
OngoingTransition Device.h Not thrown in this version.
RuntimeError Error.h Not thrown in this version. Its constructor joins all arguments to one text.

Transports, sockets and messages

Section titled “Transports, sockets and messages”
Exception Header Thrown when
TransportFactoryError TransportFactory.h TransportFactory::CreateTransportFactory() gets an unknown type. Text: Unavailable transport requested: <type>.
TransportError Transports.h A channel has an unknown transport (Unknown transport provided: <name>), or a region message gets a region of the other transport. Also when shmem cannot create, open or lock a segment or a region, when a region id already exists, when the data of a region message is outside the region, or when the region of a message is unknown. In the constructor of the shmem transport, a segment error becomes a std::runtime_error (see below).
SocketError Socket.h A socket cannot be created, or a socket option cannot be set or read. With shmem also for pub and sub sockets, and for a received message that is not a shmem message.
MessageBadAlloc Message.h shmem cannot allocate a message: the size is larger than the segment, the attempts end, or a transition interrupts the wait between two attempts.
RefCountBadAlloc Message.h shmem copies a message of an unmanaged region, and the reference count segment of the region is full.
MessageError Message.h Only in a build with FAIRMQ_DEBUG_MODE: shmem resets the transport while messages still exist.
shmem::SharedMemoryError shmem/Common.h The option shm-allocation has an unknown value, or shmem cannot find the segment or the region of a message. Also when shmem::GetDataAddressFromHandle() gets a transport that is not shmem.
shmem::Monitor::DaemonPresent shmem/Monitor.h A monitor in monitoring mode already runs for this session.
shmem::Monitor::MonitorError shmem/Monitor.h The monitor cannot find a segment, or the allocation algorithm is unknown.
zmq::Error zeromq/Common.h A socket type or a socket option name is unknown. Text: getConstant called with an invalid argument: <name>.
zmq::ContextError zeromq/Context.h The zeromq context cannot be created or configured.
tools::DefaultRouteDetectionError tools/Network.h The network interface of the default route is unknown. For a bind channel without an address, the device catches it and binds to tcp://*:1. See Network.h.

Plugins

Section titled “Plugins”
Exception Header Thrown when
PluginServices::DeviceControlError PluginServices.h A plugin calls TakeDeviceControl() or ChangeDeviceState() while another plugin controls the device.
PluginManager::BadSearchPath PluginManager.h A plugin search path is empty or is not a directory. The base class is std::invalid_argument.
PluginManager::PluginNotFound PluginManager.h The plugin manager cannot find the file of a plugin.
PluginManager::PluginLoadError PluginManager.h The plugin manager cannot load a plugin.
PluginManager::PluginInstantiationError PluginManager.h The plugin manager cannot create a plugin object.
PluginManager::ProgramOptionsParseError PluginManager.h The options of the plugin manager on the command line are not valid.

Standard exceptions

Section titled “Standard exceptions”

FairMQ also throws exceptions of the standard library and of Boost:

Exception Thrown when
std::system_error Device::ChangeStateOrThrow(): the state machine refuses the transition.
std::out_of_range A name function of States.h gets an unknown name or value. Device::GetChannel() and GetNumSubChannels() get an unknown channel. The property transport of the device has an unknown value.
std::runtime_error In BINDING, a channel cannot bind. In CONNECTING, the time init-timeout ends. In INITIALIZING DEVICE, a channel has no method. Device::NewPoller() gets channels with different transports. The shmem transport cannot start: failed creating context, reason: … or Could not initialize shared memory transport: ….
std::bad_alloc zeromq cannot allocate the buffer of a message with an alignment (malloc() fails). A shmem socket cannot allocate the zeromq message for the metadata.
boost::bad_any_cast GetProperty<T>() with a type T that is not the type of the property.
boost::program_options::error The command line has a value that is not valid for its option, or a required option is missing.

In a hook, each of these exceptions moves the device to ERROR. See Device states. The config plugin is different: it catches the exceptions of the parsers for --mq-config and --channel-config, and logs their text with the severity error. The device then starts without these channels.

Section titled “Related pages”