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.