.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ZeroMQ::Socket 3pm"
.TH ZeroMQ::Socket 3pm "2012-10-16" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ZeroMQ::Socket \- A 0MQ Socket object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use ZeroMQ qw/:all/;
\&  
\&  my $cxt = ZeroMQ::Context\->new;
\&  my $sock = ZeroMQ::Socket\->new($cxt, ZMQ_REP);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
0MQ sockets present an abstraction of a asynchronous message queue,
with the exact queueing semantics depending on the socket type in use.
.SS "Key differences to conventional sockets"
.IX Subsection "Key differences to conventional sockets"
Quoting the 0MQ manual:
.PP
Generally speaking, conventional sockets present a synchronous interface
to either connection-oriented reliable byte streams (\f(CW\*(C`SOCK_STREAM\*(C'\fR),
or connection-less unreliable datagrams (\f(CW\*(C`SOCK_DGRAM\*(C'\fR). 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.
.PP
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.
.PP
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 \f(CW\*(C`ZMQ_PAIR\*(C'\fR, 0MQ sockets may be
connected to multiple endpoints using c<\fIconnect()\fR>, while simultaneously
accepting incoming connections from multiple endpoints bound to the socket
using c<\fIbind()\fR>, thus allowing many-to-many relationships.
.SS "Socket types"
.IX Subsection "Socket types"
For detailed explanations of the socket types, check the official
0MQ documentation. This is just a short list of types:
.IP "Request-reply pattern" 2
.IX Item "Request-reply pattern"
The \f(CW\*(C`ZMQ_REQ\*(C'\fR type is for the client that sends, then receives.
The \f(CW\*(C`ZMQ_REP\*(C'\fR type is for the server that receives a message, then answers.
.IP "Publish-subscribe pattern" 2
.IX Item "Publish-subscribe pattern"
The \f(CW\*(C`ZMQ_PUB\*(C'\fR type is for publishing messages to an arbitrary number of
subscribers only. The \f(CW\*(C`ZMQ_SUB\*(C'\fR type is for subscribers that receive messages.
.IP "Pipeline pattern" 2
.IX Item "Pipeline pattern"
The \f(CW\*(C`ZMQ_UPSTREAM\*(C'\fR socket type sends messages in a pipeline pattern.
\&\f(CW\*(C`ZMQ_DOWNSTREAM\*(C'\fR receives them.
.IP "Exclusive pair pattern" 2
.IX Item "Exclusive pair pattern"
The \f(CW\*(C`ZMQ_PAIR\*(C'\fR type allows bidirectional message passing between two
participants.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Creates a new \f(CW\*(C`ZeroMQ::Socket\*(C'\fR.
.PP
First argument must be the ZeroMQ::Context in which the socket
is to live. Second argument is the socket type.
.PP
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 \f(CW\*(C`connect\*(C'\fR
method or at least one endpoint must be created for accepting
incoming connections with the \f(CW\*(C`bind\*(C'\fR method.
.SS "bind"
.IX Subsection "bind"
The \f(CW\*(C`bind($endpoint)\*(C'\fR method function creates an endpoint for accepting
connections and binds it to the socket.
.PP
Quoting the 0MQ manual:
The endpoint argument is a string consisting of two parts as
follows: \f(CW\*(C`transport://address\*(C'\fR. The transport part specifies the
underlying transport protocol to use. The meaning of the address part
is specific to the underlying transport protocol selected.
.PP
The following transports are defined. Refer to the 0MQ manual for
details.
.IP "inproc" 2
.IX Item "inproc"
Local in-process (inter-thread) communication transport.
.IP "ipc" 2
.IX Item "ipc"
Local inter-process communication transport.
.IP "tcp" 2
.IX Item "tcp"
Unicast transport using \s-1TCP.\s0
.IP "pgm, epgm" 2
.IX Item "pgm, epgm"
Reliable multicast transport using \s-1PGM.\s0
.PP
With the exception of \f(CW\*(C`ZMQ_PAIR\*(C'\fR sockets, a single socket may be connected
to multiple endpoints using \f(CW\*(C`connect($endpoint)\*(C'\fR, while simultaneously
accepting incoming connections from multiple endpoints bound to the socket
using \f(CW\*(C`bind($endpoint\*(C'\fR)>. The exact semantics depend on the socket type.
.SS "connect"
.IX Subsection "connect"
Connect to an existing endpoint. Takes an enpoint string as argument,
see the documentation for \f(CW\*(C`bind($endpoint)\*(C'\fR above.
.SS "close"
.IX Subsection "close"
.SS "send"
.IX Subsection "send"
The \f(CW\*(C`send($msg, $flags)\*(C'\fR method queues the given message to be sent to the
socket. The flags argument is a combination of the flags defined below.
.ie n .SS "send_as( $type, $message, $flags )"
.el .SS "send_as( \f(CW$type\fP, \f(CW$message\fP, \f(CW$flags\fP )"
.IX Subsection "send_as( $type, $message, $flags )"
.IP "\s-1ZMQ_NOBLOCK\s0" 2
.IX Item "ZMQ_NOBLOCK"
Specifies that the operation should be performed in non-blocking mode.
If the message cannot be queued on the socket, the \f(CW\*(C`send()\*(C'\fR method
fails with errno set to \s-1EAGAIN.\s0
.IP "\s-1ZMQ_SNDMORE\s0" 2
.IX Item "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.
.SS "recv"
.IX Subsection "recv"
The \f(CW\*(C`my $msg = $sock\->recv($flags)\*(C'\fR method receives a message from
the socket and returns it as a new \f(CW\*(C`ZeroMQ::Message\*(C'\fR object.
If there are no messages available on the specified socket
the \f(CW\*(C`recv()\*(C'\fR method blocks until the request can be satisfied.
The flags argument is a combination of the flags defined below.
.ie n .SS "recv_as( $type, $flags )"
.el .SS "recv_as( \f(CW$type\fP, \f(CW$flags\fP )"
.IX Subsection "recv_as( $type, $flags )"
.IP "\s-1ZMQ_NOBLOCK\s0" 2
.IX Item "ZMQ_NOBLOCK"
Specifies that the operation should be performed in non-blocking mode.
If there are no messages available on the specified socket, the
\&\f(CW\*(C`$sock\->recv(ZMQ_NOBLOCK)\*(C'\fR method call returns \f(CW\*(C`undef\*(C'\fR and sets \f(CW$ERRNO\fR
to \f(CW\*(C`EAGAIN\*(C'\fR.
.SS "getsockopt"
.IX Subsection "getsockopt"
The \f(CW\*(C`my $optval = $sock\->getsockopt(ZMQ_SOME_OPTION)\*(C'\fR method call
retrieves the value for the given socket option.
.PP
The following options can be retrieved. For a full explanation
of the options, please refer to the 0MQ manual.
.IP "\s-1ZMQ_RCVMORE:\s0 More message parts to follow" 2
.IX Item "ZMQ_RCVMORE: More message parts to follow"
.PD 0
.IP "\s-1ZMQ_HWM:\s0 Retrieve high water mark" 2
.IX Item "ZMQ_HWM: Retrieve high water mark"
.IP "\s-1ZMQ_SWAP:\s0 Retrieve disk offload size" 2
.IX Item "ZMQ_SWAP: Retrieve disk offload size"
.IP "\s-1ZMQ_AFFINITY:\s0 Retrieve I/O thread affinity" 2
.IX Item "ZMQ_AFFINITY: Retrieve I/O thread affinity"
.IP "\s-1ZMQ_IDENTITY:\s0 Retrieve socket identity" 2
.IX Item "ZMQ_IDENTITY: Retrieve socket identity"
.IP "\s-1ZMQ_RATE:\s0 Retrieve multicast data rate" 2
.IX Item "ZMQ_RATE: Retrieve multicast data rate"
.IP "\s-1ZMQ_RECOVERY_IVL:\s0 Get multicast recovery interval" 2
.IX Item "ZMQ_RECOVERY_IVL: Get multicast recovery interval"
.IP "\s-1ZMQ_MCAST_LOOP:\s0 Control multicast loopback" 2
.IX Item "ZMQ_MCAST_LOOP: Control multicast loopback"
.IP "\s-1ZMQ_SNDBUF:\s0 Retrieve kernel transmit buffer size" 2
.IX Item "ZMQ_SNDBUF: Retrieve kernel transmit buffer size"
.IP "\s-1ZMQ_RCVBUF:\s0 Retrieve kernel receive buffer size" 2
.IX Item "ZMQ_RCVBUF: Retrieve kernel receive buffer size"
.PD
.SS "setsockopt"
.IX Subsection "setsockopt"
The \f(CW\*(C`$sock\->setsockopt(ZMQ_SOME_OPTION, $value)\*(C'\fR method call
sets the specified option to the given value.
.PP
The following socket options can be set. For details, please
refer to the 0MQ manual:
.IP "\s-1ZMQ_HWM:\s0 Set high water mark" 2
.IX Item "ZMQ_HWM: Set high water mark"
.PD 0
.IP "\s-1ZMQ_SWAP:\s0 Set disk offload size" 2
.IX Item "ZMQ_SWAP: Set disk offload size"
.IP "\s-1ZMQ_AFFINITY:\s0 Set I/O thread affinity" 2
.IX Item "ZMQ_AFFINITY: Set I/O thread affinity"
.IP "\s-1ZMQ_IDENTITY:\s0 Set socket identity" 2
.IX Item "ZMQ_IDENTITY: Set socket identity"
.IP "\s-1ZMQ_SUBSCRIBE:\s0 Establish message filter" 2
.IX Item "ZMQ_SUBSCRIBE: Establish message filter"
.IP "\s-1ZMQ_UNSUBSCRIBE:\s0 Remove message filter" 2
.IX Item "ZMQ_UNSUBSCRIBE: Remove message filter"
.IP "\s-1ZMQ_RATE:\s0 Set multicast data rate" 2
.IX Item "ZMQ_RATE: Set multicast data rate"
.IP "\s-1ZMQ_RECOVERY_IVL:\s0 Set multicast recovery interval" 2
.IX Item "ZMQ_RECOVERY_IVL: Set multicast recovery interval"
.IP "\s-1ZMQ_MCAST_LOOP:\s0 Control multicast loopback" 2
.IX Item "ZMQ_MCAST_LOOP: Control multicast loopback"
.IP "\s-1ZMQ_SNDBUF:\s0 Set kernel transmit buffer size" 2
.IX Item "ZMQ_SNDBUF: Set kernel transmit buffer size"
.IP "\s-1ZMQ_RCVBUF:\s0 Set kernel receive buffer size" 2
.IX Item "ZMQ_RCVBUF: Set kernel receive buffer size"
.PD
.SH "CAVEATS"
.IX Header "CAVEATS"
\&\f(CW\*(C`ZeroMQ::Socket\*(C'\fR 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 \f(CW\*(C`undef\*(C'\fR in the new thread.
This makes the Perl wrapper thread safe (i.e. no segmentation faults).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
ZeroMQ, ZeroMQ::Socket
.PP
<http://zeromq.org>
.PP
ExtUtils::XSpp, Module::Build::WithXSpp
.SH "AUTHOR"
.IX Header "AUTHOR"
Daisuke Maki <daisuke@endeworks.jp>
.PP
Steffen Mueller, <smueller@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
The ZeroMQ module is
.PP
Copyright (C) 2010 by Daisuke Maki
.PP
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.