NAME¶
ZeroMQ::Socket - A 0MQ Socket object
SYNOPSIS¶
use ZeroMQ qw/:all/;
my $cxt = ZeroMQ::Context->new;
my $sock = ZeroMQ::Socket->new($cxt, ZMQ_REP);
DESCRIPTION¶
0MQ sockets present an abstraction of a asynchronous message queue, with the
exact queueing semantics depending on the socket type in use.
Key differences to conventional sockets¶
Quoting the 0MQ manual:
Generally speaking, conventional sockets present a synchronous interface to
either connection-oriented reliable byte streams ("SOCK_STREAM"), or
connection-less unreliable datagrams ("SOCK_DGRAM"). In comparison,
0MQ sockets present an abstraction of an asynchronous message queue, with the
exact queueing semantics depending on the socket type in use. Where
conventional sockets transfer streams of bytes or discrete datagrams, 0MQ
sockets transfer discrete messages.
0MQ sockets being asynchronous means that the timings of the physical connection
setup and teardown, reconnect and effective delivery are transparent to the
user and organized by 0MQ itself. Further, messages may be queued in the event
that a peer is unavailable to receive them.
Conventional sockets allow only strict one-to-one (two peers), many-to-one (many
clients, one server), or in some cases one-to-many (multicast) relationships.
With the exception of "ZMQ_PAIR", 0MQ sockets may be connected to
multiple endpoints using c<
connect()>, while simultaneously
accepting incoming connections from multiple endpoints bound to the socket
using c<
bind()>, thus allowing many-to-many relationships.
Socket types¶
For detailed explanations of the socket types, check the official 0MQ
documentation. This is just a short list of types:
- Request-reply pattern
- The "ZMQ_REQ" type is for the client that sends, then receives.
The "ZMQ_REP" type is for the server that receives a message,
then answers.
- Publish-subscribe pattern
- The "ZMQ_PUB" type is for publishing messages to an arbitrary
number of subscribers only. The "ZMQ_SUB" type is for
subscribers that receive messages.
- Pipeline pattern
- The "ZMQ_UPSTREAM" socket type sends messages in a pipeline
pattern. "ZMQ_DOWNSTREAM" receives them.
- Exclusive pair pattern
- The "ZMQ_PAIR" type allows bidirectional message passing between
two participants.
METHODS¶
new¶
Creates a new "ZeroMQ::Socket".
First argument must be the ZeroMQ::Context in which the socket is to live.
Second argument is the socket type.
The newly created socket is initially unbound, and not associated with any
endpoints. In order to establish a message flow a socket must first be
connected to at least one endpoint with the "connect" method or at
least one endpoint must be created for accepting incoming connections with the
"bind" method.
bind¶
The "bind($endpoint)" method function creates an endpoint for
accepting connections and binds it to the socket.
Quoting the 0MQ manual: The endpoint argument is a string consisting of two
parts as follows: "
transport://address". The transport part
specifies the underlying transport protocol to use. The meaning of the address
part is specific to the underlying transport protocol selected.
The following transports are defined. Refer to the 0MQ manual for details.
- inproc
- Local in-process (inter-thread) communication transport.
- ipc
- Local inter-process communication transport.
- tcp
- Unicast transport using TCP.
- pgm, epgm
- Reliable multicast transport using PGM.
With the exception of "ZMQ_PAIR" sockets, a single socket may be
connected to multiple endpoints using "connect($endpoint)", while
simultaneously accepting incoming connections from multiple endpoints bound to
the socket using "bind($endpoint")>. The exact semantics depend
on the socket type.
connect¶
Connect to an existing endpoint. Takes an enpoint string as argument, see the
documentation for "bind($endpoint)" above.
close¶
send¶
The "send($msg, $flags)" method queues the given message to be sent to
the socket. The flags argument is a combination of the flags defined below.
send_as( $type, $message, $flags )¶
- ZMQ_NOBLOCK
- Specifies that the operation should be performed in non-blocking mode. If
the message cannot be queued on the socket, the "send()" method
fails with errno set to EAGAIN.
- ZMQ_SNDMORE
- Specifies that the message being sent is a multi-part message, and that
further message parts are to follow. Refer to the 0MQ manual for details
regarding multi-part messages.
recv¶
The "my $msg = $sock->recv($flags)" method receives a message from
the socket and returns it as a new "ZeroMQ::Message" object. If
there are no messages available on the specified socket the "recv()"
method blocks until the request can be satisfied. The flags argument is a
combination of the flags defined below.
recv_as( $type, $flags )¶
- ZMQ_NOBLOCK
- Specifies that the operation should be performed in non-blocking mode. If
there are no messages available on the specified socket, the
"$sock->recv(ZMQ_NOBLOCK)" method call returns
"undef" and sets $ERRNO to "EAGAIN".
getsockopt¶
The "my $optval = $sock->getsockopt(ZMQ_SOME_OPTION)" method call
retrieves the value for the given socket option.
The following options can be retrieved. For a full explanation of the options,
please refer to the 0MQ manual.
- ZMQ_RCVMORE: More message parts to follow
- ZMQ_HWM: Retrieve high water mark
- ZMQ_SWAP: Retrieve disk offload size
- ZMQ_AFFINITY: Retrieve I/O thread affinity
- ZMQ_IDENTITY: Retrieve socket identity
- ZMQ_RATE: Retrieve multicast data rate
- ZMQ_RECOVERY_IVL: Get multicast recovery interval
- ZMQ_MCAST_LOOP: Control multicast loopback
- ZMQ_SNDBUF: Retrieve kernel transmit buffer size
- ZMQ_RCVBUF: Retrieve kernel receive buffer size
setsockopt¶
The "$sock->setsockopt(ZMQ_SOME_OPTION, $value)" method call sets
the specified option to the given value.
The following socket options can be set. For details, please refer to the 0MQ
manual:
- ZMQ_HWM: Set high water mark
- ZMQ_SWAP: Set disk offload size
- ZMQ_AFFINITY: Set I/O thread affinity
- ZMQ_IDENTITY: Set socket identity
- ZMQ_SUBSCRIBE: Establish message filter
- ZMQ_UNSUBSCRIBE: Remove message filter
- ZMQ_RATE: Set multicast data rate
- ZMQ_RECOVERY_IVL: Set multicast recovery interval
- ZMQ_MCAST_LOOP: Control multicast loopback
- ZMQ_SNDBUF: Set kernel transmit buffer size
- ZMQ_RCVBUF: Set kernel receive buffer size
CAVEATS¶
"ZeroMQ::Socket" objects aren't thread safe due to the underlying
library. Therefore, they are currently not cloned when a new Perl ithread is
spawned. The variables in the new thread that contained the socket in the
parent thread will be a scalar reference to "undef" in the new
thread. This makes the Perl wrapper thread safe (i.e. no segmentation faults).
SEE ALSO¶
ZeroMQ, ZeroMQ::Socket
<
http://zeromq.org>
ExtUtils::XSpp, Module::Build::WithXSpp
AUTHOR¶
Daisuke Maki <daisuke@endeworks.jp>
Steffen Mueller, <smueller@cpan.org>
COPYRIGHT AND LICENSE¶
The ZeroMQ module is
Copyright (C) 2010 by Daisuke Maki
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself, either Perl version 5.8.0 or, at your option,
any later version of Perl 5 you may have available.