.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "ZMQ::FFI 3pm"
.TH ZMQ::FFI 3pm "2023-08-04" "perl v5.36.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"
ZMQ::FFI \- version agnostic Perl bindings for zeromq using ffi
.SH "VERSION"
.IX Header "VERSION"
version 1.19
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    #### send/recv ####
\&
\&    use 5.012;
\&    use ZMQ::FFI qw(ZMQ_REQ ZMQ_REP);
\&
\&    my $endpoint = "ipc://zmq\-ffi\-$$";
\&    my $ctx      = ZMQ::FFI\->new();
\&
\&    my $s1 = $ctx\->socket(ZMQ_REQ);
\&    $s1\->connect($endpoint);
\&
\&    my $s2 = $ctx\->socket(ZMQ_REP);
\&    $s2\->bind($endpoint);
\&
\&    $s1\->send(\*(Aqohhai\*(Aq);
\&
\&    say $s2\->recv();
\&    # ohhai
\&
\&
\&    #### pub/sub ####
\&
\&    use 5.012;
\&    use ZMQ::FFI qw(ZMQ_PUB ZMQ_SUB);
\&    use Time::HiRes q(usleep);
\&
\&    my $endpoint = "ipc://zmq\-ffi\-$$";
\&    my $ctx      = ZMQ::FFI\->new();
\&
\&    my $s = $ctx\->socket(ZMQ_SUB);
\&    my $p = $ctx\->socket(ZMQ_PUB);
\&
\&    $s\->connect($endpoint);
\&    $p\->bind($endpoint);
\&
\&    # all topics
\&    {
\&        $s\->subscribe(\*(Aq\*(Aq);
\&
\&        until ($s\->has_pollin) {
\&            # compensate for slow subscriber
\&            usleep 100_000;
\&            $p\->send(\*(Aqohhai\*(Aq);
\&        }
\&
\&        say $s\->recv();
\&        # ohhai
\&
\&        $s\->unsubscribe(\*(Aq\*(Aq);
\&    }
\&
\&    # specific topics
\&    {
\&        $s\->subscribe(\*(Aqtopic1\*(Aq);
\&        $s\->subscribe(\*(Aqtopic2\*(Aq);
\&
\&        until ($s\->has_pollin) {
\&            usleep 100_000;
\&            $p\->send(\*(Aqtopic1 ohhai\*(Aq);
\&            $p\->send(\*(Aqtopic2 ohhai\*(Aq);
\&        }
\&
\&        while ($s\->has_pollin) {
\&            say join \*(Aq \*(Aq, $s\->recv();
\&            # topic1 ohhai
\&            # topic2 ohhai
\&        }
\&    }
\&
\&
\&    #### multipart ####
\&
\&    use 5.012;
\&    use ZMQ::FFI qw(ZMQ_DEALER ZMQ_ROUTER);
\&
\&    my $endpoint = "ipc://zmq\-ffi\-$$";
\&    my $ctx      = ZMQ::FFI\->new();
\&
\&    my $d = $ctx\->socket(ZMQ_DEALER);
\&    $d\->set_identity(\*(Aqdealer\*(Aq);
\&
\&    my $r = $ctx\->socket(ZMQ_ROUTER);
\&
\&    $d\->connect($endpoint);
\&    $r\->bind($endpoint);
\&
\&    $d\->send_multipart([qw(ABC DEF GHI)]);
\&
\&    say join \*(Aq \*(Aq, $r\->recv_multipart;
\&    # dealer ABC DEF GHI
\&
\&
\&    #### nonblocking ####
\&
\&    use 5.012;
\&    use ZMQ::FFI qw(ZMQ_PUSH ZMQ_PULL);
\&    use AnyEvent;
\&    use EV;
\&
\&    my $endpoint = "ipc://zmq\-ffi\-$$";
\&    my $ctx      = ZMQ::FFI\->new();
\&    my @messages = qw(foo bar baz);
\&
\&
\&    my $pull = $ctx\->socket(ZMQ_PULL);
\&    $pull\->bind($endpoint);
\&
\&    my $fd = $pull\->get_fd();
\&
\&    my $recv = 0;
\&    my $w = AE::io $fd, 0, sub {
\&        while ( $pull\->has_pollin ) {
\&            say $pull\->recv();
\&            # foo, bar, baz
\&
\&            $recv++;
\&            if ($recv == 3) {
\&                EV::break();
\&            }
\&        }
\&    };
\&
\&
\&    my $push = $ctx\->socket(ZMQ_PUSH);
\&    $push\->connect($endpoint);
\&
\&    my $sent = 0;
\&    my $t;
\&    $t = AE::timer 0, .1, sub {
\&        $push\->send($messages[$sent]);
\&
\&        $sent++;
\&        if ($sent == 3) {
\&            undef $t;
\&        }
\&    };
\&
\&    EV::run();
\&
\&
\&    #### specifying versions ####
\&
\&    use ZMQ::FFI;
\&
\&    # 2.x context
\&    my $ctx = ZMQ::FFI\->new( soname => \*(Aqlibzmq.so.1\*(Aq );
\&    my ($major, $minor, $patch) = $ctx\->version;
\&
\&    # 3.x context
\&    my $ctx = ZMQ::FFI\->new( soname => \*(Aqlibzmq.so.3\*(Aq );
\&    my ($major, $minor, $patch) = $ctx\->version;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1ZMQ::FFI\s0 exposes a high level, transparent, \s-1OO\s0 interface to zeromq independent
of the underlying libzmq version.  Where semantics differ, it will dispatch to
the appropriate backend for you.  As it uses ffi, there is no dependency on \s-1XS\s0
or compilation.
.PP
As of 1.00 \s-1ZMQ::FFI\s0 is implemented using FFI::Platypus. This version has
substantial performance improvements and you are encouraged to use 1.00 or
newer.
.SH "CONTEXT API"
.IX Header "CONTEXT API"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    my $ctx = ZMQ::FFI\->new(%options);
.Ve
.PP
returns a new context object, appropriate for the version of
libzmq found on your system. It accepts the following optional attributes:
.PP
\fIoptions\fR
.IX Subsection "options"
.IP "threads" 4
.IX Item "threads"
zeromq thread pool size. Default: 1
.IP "max_sockets" 4
.IX Item "max_sockets"
\&\fIrequires zmq >= 3.x\fR
.Sp
max number of sockets allowed for context. Default: 1024
.IP "soname" 4
.IX Item "soname"
.Vb 2
\&    ZMQ::FFI\->new( soname => \*(Aq/path/to/libzmq.so\*(Aq );
\&    ZMQ::FFI\->new( soname => \*(Aqlibzmq.so.3\*(Aq );
.Ve
.Sp
specify the libzmq library name to load.  By default \s-1ZMQ::FFI\s0 will first try
the generic soname for the system, then the soname for each version of zeromq
(e.g. libzmq.so.3). \f(CW\*(C`soname\*(C'\fR can also be the path to a particular libzmq so
file
.Sp
It is technically possible to have multiple contexts of different versions in
the same process, though the utility of doing such a thing is dubious
.SS "version"
.IX Subsection "version"
.Vb 1
\&    my ($major, $minor, $patch) = $ctx\->version();
.Ve
.PP
return the libzmq version as the list \f(CW\*(C`($major, $minor, $patch)\*(C'\fR
.SS "get"
.IX Subsection "get"
\&\fIrequires zmq >= 3.x\fR
.PP
.Vb 1
\&    my $threads = $ctx\->get(ZMQ_IO_THREADS)
.Ve
.PP
get a context option value
.SS "set"
.IX Subsection "set"
\&\fIrequires zmq >= 3.x\fR
.PP
.Vb 1
\&    $ctx\->set(ZMQ_MAX_SOCKETS, 42)
.Ve
.PP
set a context option value
.SS "socket"
.IX Subsection "socket"
.Vb 1
\&    my $socket = $ctx\->socket(ZMQ_REQ)
.Ve
.PP
returns a socket of the specified type. See \*(L"\s-1SOCKET API\*(R"\s0 below
.SS "proxy"
.IX Subsection "proxy"
.Vb 1
\&    $ctx\->proxy($frontend, $backend);
\&
\&    $ctx\->proxy($frontend, $backend, $capture);
.Ve
.PP
sets up and runs a \f(CW\*(C`zmq_proxy\*(C'\fR. For zmq 2.x this will use a \f(CW\*(C`ZMQ_STREAMER\*(C'\fR
device to simulate the proxy. The optional \f(CW$capture\fR is only supported for
zmq >= 3.x however
.SS "device"
.IX Subsection "device"
\&\fIzmq 2.x only\fR
.PP
.Vb 1
\&    $ctx\->device($type, $frontend, $backend);
.Ve
.PP
sets up and runs a \f(CW\*(C`zmq_device\*(C'\fR with specified frontend and backend sockets
.SS "destroy"
.IX Subsection "destroy"
destroy the underlying zmq context. In general you shouldn't have to call this
directly as it is called automatically for you when the object gets reaped
.PP
See \*(L"\s-1CLEANUP\*(R"\s0 below
.SH "SOCKET API"
.IX Header "SOCKET API"
The following \s-1API\s0 is available on socket objects created by \f(CW\*(C`$ctx\->socket\*(C'\fR.
.PP
For core attributes and functions, common across all versions of zeromq,
convenience methods are provided. Otherwise, generic get/set methods are
provided that will work independent of version.
.PP
As attributes are constantly being added/removed from zeromq, it is unlikely
the 'static' accessors will grow much beyond the current set.
.SS "version"
.IX Subsection "version"
.Vb 1
\&    my ($major, $minor, $patch) = $socket\->version();
.Ve
.PP
same as Context \f(CW\*(C`version\*(C'\fR above
.SS "connect"
.IX Subsection "connect"
.Vb 1
\&    $socket\->connect($endpoint);
.Ve
.PP
does socket connect on the specified endpoint
.SS "disconnect"
.IX Subsection "disconnect"
\&\fIrequires zmq >= 3.x\fR
.PP
.Vb 1
\&    $socket\->disconnect($endpoint);
.Ve
.PP
does socket disconnect on the specified endpoint
.SS "bind"
.IX Subsection "bind"
.Vb 1
\&    $socket\->bind($endpoint);
.Ve
.PP
does socket bind on the specified endpoint
.SS "unbind"
.IX Subsection "unbind"
\&\fIrequires zmq >= 3.x\fR
.PP
.Vb 1
\&    $socket\->unbind($endpoint);
.Ve
.PP
does socket unbind on the specified endpoint
.SS "get_linger, set_linger"
.IX Subsection "get_linger, set_linger"
.Vb 1
\&    my $linger = $socket\->get_linger();
\&
\&    $socket\->set_linger($millis);
.Ve
.PP
get or set the socket linger period. Default: 0 (no linger)
.PP
See \*(L"\s-1CLEANUP\*(R"\s0 below
.SS "get_identity, set_identity"
.IX Subsection "get_identity, set_identity"
.Vb 1
\&    my $ident = $socket\->get_identity();
\&
\&    $socket\->set_identity($ident);
.Ve
.PP
get or set the socket identity for request/reply patterns
.SS "get_fd"
.IX Subsection "get_fd"
.Vb 1
\&    my $fd = $socket\->get_fd();
.Ve
.PP
get the file descriptor associated with the socket
.SS "get"
.IX Subsection "get"
.Vb 1
\&    my $option_value = $socket\->get($option_name, $option_type);
\&
\&    my $linger = $socket\->get(ZMQ_LINGER, \*(Aqint\*(Aq);
.Ve
.PP
generic method to get the value for any socket option. \f(CW$option_type\fR is the
type associated with \f(CW$option_value\fR in the zeromq \s-1API\s0 (\f(CW\*(C`zmq_getsockopt\*(C'\fR man
page)
.SS "set"
.IX Subsection "set"
.Vb 1
\&    $socket\->set($option_name, $option_type, $option_value);
\&
\&    $socket\->set(ZMQ_IDENTITY, \*(Aqbinary\*(Aq, \*(Aqfoo\*(Aq);
.Ve
.PP
generic method to set the value for any socket option.  \f(CW$option_type\fR is the
type associated with \f(CW$option_value\fR in the zeromq \s-1API\s0 (\f(CW\*(C`zmq_setsockopt\*(C'\fR man
page)
.SS "subscribe"
.IX Subsection "subscribe"
.Vb 1
\&    $socket\->subscribe($topic);
.Ve
.PP
add \f(CW$topic\fR to the subscription list
.SS "unsubscribe"
.IX Subsection "unsubscribe"
.Vb 1
\&    $socket\->unsubscribe($topic);
.Ve
.PP
remove \f(CW$topic\fR from the subscription list
.SS "send"
.IX Subsection "send"
.Vb 1
\&    $socket\->send($msg);
\&
\&    $socket\->send($msg, $flags);
.Ve
.PP
sends a message using the optional flags
.SS "send_multipart"
.IX Subsection "send_multipart"
.Vb 1
\&    $socket\->send($parts_aref);
\&
\&    $socket\->send($parts_aref, $flags);
.Ve
.PP
given an array ref of message parts, sends the multipart message using the
optional flags. \s-1ZMQ_SNDMORE\s0 semantics are handled for you
.SS "recv"
.IX Subsection "recv"
.Vb 1
\&    my $msg = $socket\->recv();
\&
\&    my $msg = $socket\->recv($flags);
.Ve
.PP
receives a message using the optional flags
.SS "recv_multipart"
.IX Subsection "recv_multipart"
.Vb 1
\&    my @parts = $socket\->recv_multipart();
\&
\&    my @parts = $socket\->recv_multipart($flags);
.Ve
.PP
receives a multipart message, returning an array of parts. \s-1ZMQ_RCVMORE\s0
semantics are handled for you
.SS "has_pollin, has_pollout"
.IX Subsection "has_pollin, has_pollout"
.Vb 1
\&    while ( $socket\->has_pollin ) { ... }
.Ve
.PP
checks \s-1ZMQ_EVENTS\s0 for \s-1ZMQ_POLLIN\s0 and \s-1ZMQ_POLLOUT\s0 respectively, and returns
true/false depending on the state
.SS "close"
.IX Subsection "close"
close the underlying zmq socket. In general you shouldn't have to call this
directly as it is called automatically for you when the object gets reaped
.PP
See \*(L"\s-1CLEANUP\*(R"\s0 below
.SS "die_on_error"
.IX Subsection "die_on_error"
.Vb 1
\&    $socket\->die_on_error(0);
\&
\&    $socket\->die_on_error(1);
.Ve
.PP
controls whether error handling should be exceptional or not. This is set to
true by default. See \*(L"\s-1ERROR HANDLING\*(R"\s0 below
.SS "has_error"
.IX Subsection "has_error"
returns true or false depending on whether the last socket operation had an
error. This is really just an alias for \f(CW\*(C`last_errno\*(C'\fR
.SS "last_errno"
.IX Subsection "last_errno"
returns the system \f(CW\*(C`errno\*(C'\fR set by the last socket operation, or 0 if there
was no error
.SS "last_strerror"
.IX Subsection "last_strerror"
returns the human readable system error message associated with the socket
\&\f(CW\*(C`last_errno\*(C'\fR
.SH "CLEANUP"
.IX Header "CLEANUP"
With respect to cleanup \f(CW\*(C`ZMQ::FFI\*(C'\fR follows either the zeromq guide <http://zguide.zeromq.org/page:all#Making-a-Clean-Exit>
recommendations or the behavior of other zmq bindings.
That is:
.IP "\(bu" 4
it uses 0 linger by default (this is the default used by czmq <https://github.com/zeromq/czmq> and jzmq <https://github.com/zeromq/jzmq>)
.IP "\(bu" 4
during object destruction it will call close/destroy for you
.IP "\(bu" 4
it arranges the reference hierarchy such that sockets will be properly
      cleaned up before their associated contexts
.IP "\(bu" 4
it detects fork/thread situations and ensures sockets/contexts are only
      cleaned up in their originating process/thread
.IP "\(bu" 4
it guards against double closes/destroys
.PP
Given the above you're probably better off letting \f(CW\*(C`ZMQ::FFI\*(C'\fR handle cleanup
for you. But if for some reason you want to do explicit cleanup yourself you
can. All the below will accomplish the same thing:
.PP
.Vb 7
\&    # implicit cleanup
\&    {
\&        my $context = ZMQ::FFI\->new();
\&        my $socket  = $ctx\->socket($type);
\&        ...
\&        # close/destroy called in destructors at end of scope
\&    }
\&
\&    # explicit cleanup
\&    $socket\->close();
\&    $context\->destroy();
\&
\&    # ditto
\&    undef $socket;
\&    undef $context;
.Ve
.PP
Regarding \f(CW\*(C`linger\*(C'\fR, you can always set this to a value you prefer if
you don't like the default. Once set the new value will be used when the
socket is subsequently closed (either implicitly or explicitly):
.PP
.Vb 3
\&    $socket\->set_linger(\-1); # infinite linger
\&                             # $context\->destroy will block forever
\&                             # (or until all pending messages have been sent)
.Ve
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
By default, \s-1ZMQ::FFI\s0 checks the return codes of underlying zmq functions for
you, and in the case of an error it will die with the human readable system
error message.
.PP
.Vb 2
\&    $ctx\->socket(\-1);
\&    # dies with \*(Aqzmq_socket: Invalid argument\*(Aq
.Ve
.PP
Usually this is what you want, but not always. Some zmq operations can return
errors that are not fatal and should be handled. For example using
\&\f(CW\*(C`ZMQ_DONTWAIT\*(C'\fR with send/recv can return \f(CW\*(C`EAGAIN\*(C'\fR and simply means try
again, not die.
.PP
For situations such as this you can turn off exceptional error handling by
setting \f(CW\*(C`die_on_error\*(C'\fR to 0. It is then for you to check and manage any zmq
errors by checking \f(CW\*(C`last_errno\*(C'\fR:
.PP
.Vb 1
\&    use Errno qw(EAGAIN);
\&
\&    my $ctx = ZMQ::FFI\->new();
\&    my $s   = $ctx\->socket(ZMQ_DEALER);
\&    $s\->bind(\*(Aqtcp://*:7200\*(Aq);
\&
\&    $s\->die_on_error(0); # turn off exceptional error handling
\&
\&    while (1) {
\&        my $msg = $s\->recv(ZMQ_DONTWAIT);
\&
\&        if ($s\->last_errno == EAGAIN) {
\&            sleep 1;
\&        }
\&        elsif ($s\->last_errno) {
\&            die $s\->last_strerror;
\&        }
\&        else {
\&            warn "recvd: $msg";
\&            last;
\&        }
\&    }
\&
\&    $s\->die_on_error(1); # turn back on exceptional error handling
.Ve
.SH "FFI VS XS PERFORMANCE"
.IX Header "FFI VS XS PERFORMANCE"
\&\s-1ZMQ::FFI\s0 uses FFI::Platypus on the backend. In addition to a friendly,
usable interface, FFI::Platypus's killer feature is \f(CW\*(C`attach\*(C'\fR. \f(CW\*(C`attach\*(C'\fR makes
it possible to bind ffi functions in memory as first class Perl xsubs. This
results in dramatic performance gains and gives you the flexibility of ffi
with performance approaching that of \s-1XS.\s0
.PP
Testing indicates FFI::Platypus xsubs are around 30% slower than \*(L"real\*(R" \s-1XS\s0
xsubs. That may sound like a lot, but to put it in perspective that means, for
zeromq, the \s-1XS\s0 bindings can send 10 million messages 1\-2 seconds faster than
the ffi ones.
.PP
If you really care about 1\-2 seconds over 10 million messages you should be
writing your solution in C anyways. An equivalent C implementation will be
several \fIhundred\fR percent faster or more.
.PP
Keep in mind also that the small speed bump you get using \s-1XS\s0 can easily be
wiped out by crappy and poorly optimized Perl code.
.PP
Now that Perl finally has a great ffi interface, it is hard to make the case
to continue using \s-1XS.\s0 The slight speed bump just isn't worth giving up the
convenience, flexibility, and portability of ffi.
.PP
You can find the detailed performance results that informed this section at:
<https://gist.github.com/calid/17df5bcfb81c83786d6f>
.SH "BUGS"
.IX Header "BUGS"
\&\f(CW\*(C`ZMQ::FFI\*(C'\fR is free as in beer in addition to being free as in speech. While
I've done my best to ensure it's tasty, high quality beer, it probably isn't perfect.
If you encounter problems, or otherwise see room for improvement, please open
an issue (or even better a pull request!) on github <https://github.com/zeromq/perlzmq>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
ZMQ::FFI::Constants
.IP "\(bu" 4
ZMQ::FFI::Util
.IP "\(bu" 4
FFI::Platypus
.IP "\(bu" 4
FFI::Raw
.IP "\(bu" 4
ZMQ::LibZMQ3
.SH "CREDITS"
.IX Header "CREDITS"
Thank you to the following for patches, bug reports, feedback, or suggestions:
.PP
Dave Lambley, Graham Ollis, Klaus Ita, Marc Mims, Parth Gandhi, Pawel Pabian,
Robert Hunter, Sergey KHripchenko, Slaven Rezic, Whitney Jackson, pipcet
.SH "AUTHOR"
.IX Header "AUTHOR"
Dylan Cali <calid1984@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2023 by Dylan Cali.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.