NAME¶

NanoMsg::Raw - Low-level interface to the nanomsg scalability protocols library

SYNOPSIS¶

    use Test::More;
    use NanoMsg::Raw;
    my $sb = nn_socket(AF_SP, NN_PAIR);
    nn_bind($sb, 'inproc://foo');
    my $sc = nn_socket(AF_SP, NN_PAIR);
    nn_connect($sc, 'inproc://foo');
    nn_send($sb, 'bar');
    nn_recv($sc, my $buf);
    is $buf, 'bar';

WARNING¶

nanomsg, the c library this module is based on, is still in beta stage!

DESCRIPTION¶

"NanoMsg::Raw" is a binding to the "nanomsg" C library. The goal of this module is to provide a very low-level and manual interface to all the functionality of the nanomsg library. It doesn't intend to provide a convenient high-level API, integration with event loops, or the like. Those are intended to be implemented as separate abstractions on top of "NanoMsg::Raw".

The nanomsg C library is a high-performance implementation of several "scalability protocols". Scalability protocol's job is to define how multiple applications communicate to form a single distributed application. Implementation of following scalability protocols is available at the moment:

• "PAIR" simple one-to-one communication
• "BUS" simple many-to-many communication
• "REQREP" allows one to build clusters of stateless services to process user requests
• "PUBSUB" distributes messages to large sets of interested subscribers
• "PIPELINE" aggregates messages from multiple sources and load balances them among many destinations
• "SURVEY" allows one to query state of multiple applications in a single go

Scalability protocols are layered on top of transport layer in the network stack. At the moment, nanomsg library supports following transports:

• "INPROC" transport within a process (between threads, modules etc.)
• "IPC" transport between processes on a single machine
• "TCP" network transport via TCP

nn_socket($domain, $protocol)

    my $s = nn_socket(AF_SP, NN_PAIR);
    die nn_errno unless defined $s;
    

Creates a nanomsg socket with specified $domain and $protocol. Returns a file descriptor for the newly created socket.

Following domains are defined at the moment:

nn_close($s)

    nn_close($s) or die nn_errno;
    

Closes the socket $s. Any buffered inbound messages that were not yet received by the application will be discarded. The library will try to deliver any outstanding outbound messages for the time specified by "NN_LINGER" socket option. The call will block in the meantime.

If the function succeeds, a true value is returned. Otherwise, "undef" is returned and "nn_errno" is set to to one of the values defined below.

nn_setsockopt($s, $level, $option, $value)

    nn_setsockopt($s, NN_SOL_SOCKET, NN_LINGER, 1000) or die nn_errno;
    nn_setsockopt($s, NN_SOL_SOCKET, NN_SUB_SUBSCRIBE, 'ABC') or die nn_errno;
    

Sets the $value of the socket option $option. The $level argument specifies the protocol level at which the option resides. For generic socket-level options use the "NN_SOL_SOCKET" level. For socket-type-specific options use the socket type for the $level argument (e.g. "NN_SUB"). For transport-specific options use the ID of the transport as the $level argument (e.g. "NN_TCP").

If the function succeeds a true value is returned. Otherwise, "undef" is returned and "nn_errno" is set to to one of the values defined below.

nn_getsockopt($s, $level, $option)

    my $linger = unpack 'i', nn_getsockopt($s, NN_SOL_SOCKET, NN_LINGER) || die nn_errno;
    

Retrieves the value for the socket option $option. The $level argument specifies the protocol level at which the option resides. For generic socket-level options use the "NN_SOL_SOCKET" level. For socket-type-specific options use the socket type for the $level argument (e.g. "NN_SUB"). For transport-specific options use ID of the transport as the $level argument (e.g. "NN_TCP").

The function returns a packed string representing the requested socket option, or "undef" on error, with one of the following reasons for the error placed in "nn_errno".

nn_bind($s, $addr)

    my $eid = nn_bind($s, 'inproc://test');
    die nn_errno unless defined $eid;
    

Adds a local endpoint to the socket $s. The endpoint can be then used by other applications to connect to.

The $addr argument consists of two parts as follows: "transport://address". The "transport" specifies the underlying transport protocol to use. The meaning of the "address" part is specific to the underlying transport protocol.

See "Transports" for a list of available transport protocols.

The maximum length of the $addr parameter is specified by "NN_SOCKADDR_MAX" constant.

Note that "nn_bind" and "nn_connect" may be called multiple times on the same socket thus allowing the socket to communicate with multiple heterogeneous endpoints.

If the function succeeds, an endpoint ID is returned. Endpoint ID can be later used to remove the endpoint from the socket via "nn_shutdown" function.

If the function fails, "undef" is returned and "nn_errno" is set to to one of the values defined below.

nn_connect($s, $addr)

    my $eid = nn_connect($s, 'inproc://test');
    die nn_errno unless defined $eid;
    

Adds a remote endpoint to the socket $s. The library would then try to connect to the specified remote endpoint.

The $addr argument consists of two parts as follows: "transport://address". The "transport" specifies the underlying transport protocol to use. The meaning of the "address" part is specific to the underlying transport protocol.

See "Protocols" for a list of available transport protocols.

The maximum length of the $addr parameter is specified by "NN_SOCKADDR_MAX" constant.

Note that "nn_connect" and "nn_bind" may be called multiple times on the same socket thus allowing the socket to communicate with multiple heterogeneous endpoints.

If the function succeeds, an endpoint ID is returned. Endpoint ID can be later used to remove the endpoint from the socket via "nn_shutdown" function.

If the function fails, "undef" is returned and "nn_errno" is set to to one of the values defined below.

nn_shutdown($s, $eid)

    nn_shutdown($s, $eid) or die nn_errno;
    

Removes an endpoint from socket $s. The "eid" parameter specifies the ID of the endpoint to remove as returned by prior call to "nn_bind" or "nn_connect".

The "nn_shutdown" call will return immediately. However, the library will try to deliver any outstanding outbound messages to the endpoint for the time specified by the "NN_LINGER" socket option.

If the function succeeds, a true value is returned. Otherwise, "undef" is returned and "nn_errno" is set to to one of the values defined below.

nn_send($s, $data, $flags=0)

    my $bytes_sent = nn_send($s, 'foo');
    die nn_errno unless defined $bytes_sent;
    

This function will send a message containing the provided $data to the socket $s.

$data can either be anything that can be used as a byte string in perl or a message buffer instance allocated by "nn_allocmsg". In case of a message buffer instance the instance will be deallocated and invalidated by the "nn_send" function. The buffer will be an instance of "NanoMsg::Raw::Message::Freed" after the call to "nn_send".

Which of the peers the message will be sent to is determined by the particular socket type.

The $flags argument, which defaults to 0, is a combination of the flags defined below:

nn_recv($s, $data, $length=NN_MSG, $flags=0)

    my $bytes_received = nn_recv($s, my $buf, 256);
    die nn_errno unless defined $bytes_received;
    

Receive a message from the socket $s and store it in the buffer $buf. Any bytes exceeding the length specified by the $length argument will be truncated.

Alternatively, "nn_recv" can allocate a message buffer instance for you. To do so, set the $length parameter to "NN_MSG" (the default).

The $flags argument, which defaults to 0, is a combination of the flags defined below:

nn_sendmsg($s, $flags, $data1, $data2, ..., $dataN)

    my $bytes_sent = nn_sendmsg($s, 0, 'foo', 'bar');
    die nn_errno unless defined $bytes_sent;
    

This function is a fine-grained alternative to "nn_send". It allows sending multiple data buffers that make up a single message without having to create another temporary buffer to hold the concatenation of the different message parts.

The scalars containing the data to be sent ($data1, $data2, ..., $dataN) can either be anything that can be used as a byte string in perl or a message buffer instance allocated by "nn_allocmsg". In case of a message buffer instance the instance will be deallocated and invalidated by the "nn_sendmsg" function. The buffers will be a instances of "NanoMsg::Raw::Message::Freed" after the call to "nn_sendmsg".

When using message buffer instances, only one buffer may be provided.

To which of the peers will the message be sent to is determined by the particular socket type.

The $flags argument is a combination of the flags defined below:

nn_recvmsg($s, $flags, $data1 => $len1, $data2 => $len2, ..., $dataN => $lenN)

    my $bytes_received = nn_recvmsg($s, 0, my $buf1 => 256, my $buf2 => 1024);
    die nn_errno unless defined $bytes_received;
    

This function is a fine-grained alternative to "nn_recv". It allows receiving a single message into multiple data buffers of different sizes, eliminating the need to create copies of part of the received message in some cases.

The scalars in which to receive the message data ($buf1, $buf2, ..., $bufN) will be filled with as many bytes of data as is specified by the length parameter following them in the argument list ($len1, $len2, ..., $lenN).

Alternatively, "nn_recvmsg" can allocate a message buffer instance for you. To do so, set the length parameter of a buffer to to "NN_MSG". In this case, only one receive buffer can be provided.

The $flags argument is a combination of the flags defined below:

nn_allocmsg($size, $type)

    my $msg = nn_allocmsg(3, 0) or die nn_errno;
    $msg->copy('foo');
    nn_send($s, $msg);
    

Allocate a message of the specified $size to be sent in zero-copy fashion. The content of the message is undefined after allocation and it should be filled in by the user. While "nn_send" and "nn_sendmsg" allow one to send arbitrary buffers, buffers allocated using "nn_allocmsg" can be more efficient for large messages as they allow for using zero-copy techniques.

The $type parameter specifies type of allocation mechanism to use. Zero is the default one. However, individual transport mechanisms may define their own allocation mechanisms, such as allocating in shared memory or allocating a memory block pinned down to a physical memory address. Such allocation, when used with the transport that defines them, should be more efficient than the default allocation mechanism.

If the function succeeds a newly allocated message buffer instance (an object instance of the class NanoMsg::Raw::Message) is returned. Otherwise, "undef" is returned and "nn_errno" is set to to one of the values defined below.

nn_errno()

Returns value of "errno" after the last call to any nanomsg function in the current thread. This function can be used in the same way the $! global variable is be used for many other system and library calls.

The return value can be used in numeric context, for example to compare it with error code constants such as "EAGAIN", or in a string context, to retrieve a textual message describing the error.

nn_strerror($errno)

Returns a textual representation of the error described by the nummeric $errno provided. It shouldn't normally be necessary to ever call this function, as using "nn_errno" in string context is basically equivalent to nn_strerror(nn_errno).

nn_device($s1, $s2)

    nn_device($s1, $s2) or die;
    

Starts a device to forward messages between two sockets. If both sockets are valid, the "nn_device" function loops and sends and messages received from $s1 to $s2 and vice versa. If only one socket is valid and the other is "undef", "nn_device" works in a loopback mode - it loops and sends any messages received from the socket back to itself.

The function loops until it hits an error. In such case it returns "undef" and sets "nn_errno" to one of the values defined below.

nn_term()

    nn_term();
    

To help with shutdown of multi-threaded programs the "nn_term" function is provided. It informs all the open sockets that process termination is underway.

If a socket is blocked inside a blocking function, such as "nn_recv", it will be unblocked and the "ETERM" error will be returned to the user. Similarly, any subsequent attempt to invoke a socket function other than "nn_close" after "nn_term" was called will result in an "ETERM" error.

If waiting for "NN_SNDFD" or "NN_RCVFD" using a polling function, such as "poll" or "select", the call will unblock with both "NN_SNDFD" and "NN_RCVFD" signaled.

The "nn_term" function itself is non-blocking.

Protocols¶

Transports¶

Constants¶

In addition to all the error constants and "NN_" constants used in the documentation of the individual functions, protocols, and transports, the following constants are available:

• "NN_VERSION_CURRENT" The current interface version.
• "NN_VERSION_REVISION" The latest revision of the current interface.
• "NN_VERSION_AGE" How many past interface versions are still supported.

SEE ALSO¶

• The nanomsg C library documentation at <http://nanomsg.org/v0.1/nanomsg.7.html> The API this module provides is very close to the C library's interface, so the C documentation is likely to be useful to developers using Perl, too. Additionally, most of this module's documentation is copied from the C library documentation, so the upstream documentation might be somewhat more recent.
• NanoMsg::Raw::Message