ZMQ::LibZMQ4(3pm)

1ZMQ::LibZMQ4(3)       User Contributed Perl Documentation      ZMQ::LibZMQ4(3)
2
3
4

NAME

6       ZMQ::LibZMQ4 - A libzmq 4.x wrapper for Perl
7

SYNOPSIS

9           use ZMQ::LibZMQ4;
10           use ZMQ::Constants; # separate module
11
12           my $ctxt = zmq_init($threads);
13           my $rv   = zmq_term($ctxt);
14
15           my $msg  = zmq_msg_init();
16           my $msg  = zmq_msg_init_size( $size );
17           my $msg  = zmq_msg_init_data( $data );
18           my $rv   = zmq_msg_close( $msg );
19           my $rv   = zmq_msg_move( $dest, $src );
20           my $rv   = zmq_msg_copy( $dest, $src );
21           my $data = zmq_msg_data( $msg );
22           my $size = zmq_msg_size( $msg);
23
24           my $sock = zmq_socket( $ctxt, $type );
25           my $rv   = zmq_close( $sock );
26           my $rv   = zmq_setsockopt( $socket, $option, $value );
27           my $val  = zmq_getsockopt( $socket, $option );
28           my $rv   = zmq_bind( $sock, $addr );
29           my $rv   = zmq_send( $sock, $buffer, $length, $flags );
30           my $msg  = zmq_sendmsg( $sock, $msg, $flags );
31           my $rv   = zmq_recv( $sock, $buffer, $length, $flags );
32           my $msg  = zmq_recvmsg( $sock, $flags );
33

INSTALLATION

35       If you have libzmq registered with pkg-config:
36
37           perl Makefile.PL
38           make
39           make test
40           make install
41
42       If you don't have pkg-config, and libzmq is installed under
43       /usr/local/libzmq:
44
45           ZMQ_HOME=/usr/local/libzmq \
46               perl Makefile.PL
47           make
48           make test
49           make install
50
51       If you want to customize include directories and such:
52
53           ZMQ_INCLUDES=/path/to/libzmq/include \
54           ZMQ_LIBS=/path/to/libzmq/lib \
55           ZMQ_H=/path/to/libzmq/include/zmq.h \
56               perl Makefile.PL
57           make
58           make test
59           make install
60
61       If you want to compile with debugging on:
62
63           perl Makefile.PL -g
64

DESCRIPTION

66       The "ZMQ::LibZMQ4" module is a wrapper of the 0MQ message passing
67       library for Perl.
68
69       Before you start using this module, please make sure you have read and
70       understood the zguide.
71
72           http://zguide.zeromq.org/page:all
73
74       For specifics on each function, please refer to their documentation for
75       the definitive explanation of each.
76
77           http://api.zeromq.org/
78
79       This module is merely a thin wrapper around the C API: You need to
80       understand how the C API works in order to properly use this module.
81
82       Note that this is a wrapper for libzmq 4.x. For 2.x, you need to check
83       ZMQ::LibZMQ2 and for 3.x, you need to check ZMQ::LibZMQ3
84

BASIC USAGE

86       Please make sure you already have ZMQ::Constants module. If you
87       installed ZMQ::LibZMQ4 from CPAN via cpan/cpanm, it should have already
88       been installed for you. All socket types and other flags are declared
89       in this module.
90
91       To start using ZMQ::LibZMQ4, you need to create a context object, then
92       as many ZMQ::LibZMQ4::Socket objects as you need:
93
94           my $ctxt = zmq_init;
95           my $socket = zmq_socket( $ctxt, ... options );
96
97       You need to call "zmq_bind()" or "zmq_connect()" on the socket,
98       depending on your usage. For example on a typical server-client model
99       you would write on the server side:
100
101           zmq_bind( $socket, "tcp://127.0.0.1:9999" );
102
103       and on the client side:
104
105           zmq_connect( $socket, "tcp://127.0.0.1:9999" );
106
107       The underlying zeromq library offers TCP, multicast, in-process, and
108       ipc connection patterns. Read the zeromq manual for more details on
109       other ways to setup the socket.
110
111       When sending data, you can either pass a ZMQ::LibZMQ4::Message object
112       or a Perl string.
113
114           # the following two send() calls are equivalent
115           my $msg = zmq_msg_init_data( "a simple message" );
116           zmq_sendmsg( $socket, $msg );
117
118           zmq_sendmsg( $socket, "a simple message" );
119
120       In most cases using ZMQ::LibZMQ4::Message is redundant, so you will
121       most likely use the string version.
122
123       To receive, simply call "zmq_recvmsg()" on the socket
124
125           my $msg = zmq_recvmsg( $socket );
126
127       The received message is an instance of ZMQ::LibZMQ4::Message object,
128       and you can access the content held in the message via the
129       "zmq_msg_data()" method:
130
131           my $data = zmq_msg_data( $msg );
132

WHEN IN DOUBT

134       0MQ is a relatively large framework, and to use it you need to be
135       comfortable with a lot of concepts. If you think this module is not
136       behaving like you expect it to, please read the documents for the C API
137

ASYNCHRONOUS I/O WITH ZEROMQ

139       By default 0MQ comes with its own zmq_poll() mechanism that can handle
140       non-blocking sockets. You can use this by calling zmq_poll with a list
141       of hashrefs:
142
143           zmq_poll([
144               {
145                   fd => fileno(STDOUT),
146                   events => ZMQ_POLLOUT,
147                   callback => \&callback,
148               },
149               {
150                   socket => $zmq_socket,
151                   events => ZMQ_POLLIN,
152                   callback => \&callback
153               },
154           ], $timeout );
155
156       Unfortunately this custom polling scheme doesn't play too well with
157       AnyEvent.
158
159       Fortunately you can use getsockopt to retrieve the underlying file
160       descriptor, so use that to integrate ZMQ::LibZMQ4 and AnyEvent:
161
162           my $socket = zmq_socket( $ctxt, ZMQ_REP );
163           my $fh = zmq_getsockopt( $socket, ZMQ_FD );
164           my $w; $w = AE::io $fh, 0, sub {
165               while ( my $msg = zmq_recv( $socket, ZMQ_RCVMORE ) ) {
166                   # do something with $msg;
167               }
168               undef $w;
169           };
170

NOTES ON MULTI-PROCESS and MULTI-THREADED USAGE

172       0MQ works on both multi-process and multi-threaded use cases, but you
173       need to be careful about sharing ZMQ::LibZMQ4 objects.
174
175       For multi-process environments, you should not be sharing the context
176       object.  Create separate contexts for each process, and therefore you
177       shouldn't be sharing the socket objects either.
178
179       For multi-thread environments, you can share the same context object.
180       However you cannot share sockets. Note that while the Perl Socket
181       objects survive between threads, their underlying C structures do not,
182       and you will get an error if you try to use them between sockets.
183

FUNCTIONS

185       ZMQ::LibZMQ4 attempts to stick to the libzmq interface as much as
186       possible. Unless there is a structural problem (say, an underlying
187       pointer that the Perl binding expects was missing), no function should
188       throw an exception.
189
190       Return values should resemble that of libzmq, except for when new data
191       is allocated and returned to the user - That includes things like
192       "zmq_init()", "zmq_socket()", "zmq_msg_data()", etc.
193
194       Where applicable, $! should be updated to match the value set by
195       libzmq, so you should be able to do:
196
197           my $cxt = zmq_init();
198           if (! $cxt) {
199               die "zmq_init() failed with $!";
200           }
201
202   $errno = zmq_errno()
203       Returns the value of errno variable for the calling thread. You
204       normally should not need to use this function. See the man page for
205       zmq_errno() provided by libzmq.
206
207   $string = zmq_strerror( $errno )
208       Returns the string representation of $errno. Use this to stringify
209       errors that libzmq provides.
210
211   $cxt = zmq_init( $threads )
212       Creates a new context object. $threads argument is optional.  Context
213       objects can be reused across threads.
214
215       Returns undef upon error, and sets $!.
216
217       Note: Deprecated in libzmq, but the Perl binding will silently fallback
218       to using "zmq_ctx_new()", if available.
219
220   $cxt = zmq_ctx_new( $threads );
221       Creates a new context object. $threads argument is optional.  Context
222       objects can be reused across threads.
223
224       Returns undef upon error, and sets $!.
225
226       Note: may not be available depending on your libzmq version.
227
228   $rv = zmq_ctx_get( $cxt, $option )
229       Gets the value for the given option.
230
231       Returns -1 status upon failure, and sets $!
232
233       Note: may not be available depending on your libzmq version.
234
235   $rv = zmq_ctx_set( $cxt, $option, $value )
236       Sets the value for the given option.
237
238       Returns a non-zero status upon failure, and sets $!.
239
240       Note: may not be available depending on your libzmq version.
241
242   $rv = zmq_term( $cxt )
243       Terminates the context. Be careful, as it might hang if you have
244       pending socket operations.
245
246       Returns a non-zero status upon failure, and sets $!.
247
248       Note: Deprecated in libzmq, but the Perl binding will silently fallback
249       to using "zmq_ctx_destroy()", if available.
250
251   $rv = zmq_ctx_destroy( $cxt )
252       Terminates the context. Be careful, as it might hang if you have
253       pending socket operations.
254
255       Returns a non-zero status upon failure, and sets $!.
256
257       Note: may not be available depending on your libzmq version.
258
259   $socket = zmq_socket( $cxt, $socket_type )
260       Creates a new socket object. $socket_types are constants declared in
261       ZMQ::Constants. Sockets cannot be reused across threads.
262
263       Returns undef upon error, and sets $!.
264
265   $rv = zmq_bind( $sock, $address )
266       Binds the socket to listen to specified $address.
267
268       Returns a non-zero status upon failure, and sets $!
269
270   $rv = zmq_unbind( $sock, $address )
271       Stops listening on this endpoint.
272
273       Returns a non-zero status upon failure, and sets $!
274
275       Note: may not be available depending on your libzmq version.
276
277   $rv = zmq_connect( $sock, $address )
278       Connects the socket to the specified $address.
279
280       Returns a non-zero status upon failure, and sets $!
281
282   $rv = zmq_disconnect( $sock, $address )
283       Disconnects the socket from the specified $address.
284
285       Returns a non-zero status upon failure, and sets $!
286
287       Note: may not be available depending on your libzmq version.
288
289   $rv = zmq_close( $sock )
290       Closes the socket explicitly.
291
292       Returns a non-zero status upon failure, and sets $!.
293
294   $value = zmq_getsockopt( $socket, $option )
295       Gets the value of the specified option.
296
297       If the particular version of ZMQ::LibZMQ4 does not implement the named
298       socket option, an exception will be thrown:
299
300           /* barfs, because we don't know what type this new option is */
301           zmq_getsockopt( $socket, ZMQ_NEW_SHINY_OPTION );
302
303       In this case you can either use ZMQ::Constants, or you can use one of
304       the utility functions that ZMQ::LibZMQ4 provides.
305
306       Using ZMQ::Constants
307           ZMQ::LibZMQ4 internally refers to ZMQ::Constants to learn about the
308           type of a socket option. You can easily add new constants to this
309           map:
310
311               use ZMQ::Constants;
312               ZMQ::Constants::add_sockopt_type( "int" => ZMQ_NEW_SHINY_OPTION );
313
314               # Then elsewhere...
315               my $value = zmq_getsockopt( $socket, ZMQ_NEW_SHINY_OPTION );
316
317       Using utilities in ZMQ::LibZMQ4
318               /* say you know that the value is an int, int64, uint64, or char *
319                  by reading the zmq docs */
320               $int    = zmq_getsockopt_int( $socket, ZMQ_NEW_SHINY_OPTION );
321               $int64  = zmq_getsockopt_int64( $socket, ZMQ_NEW_SHINY_OPTION );
322               $uint64 = zmq_getsockopt_uint64( $socket, ZMQ_NEW_SHINY_OPTION );
323               $string = zmq_getsockopt_string( $socket, ZMQ_NEW_SHINY_OPTION );
324
325   $status = zmq_setsockopt( $socket, $option, $value )
326       Sets the value of the specified option. Returns the status.
327
328       See "zmq_getsockopt()" if you have problems with ZMQ::LibZMQ4 not
329       knowing the type of the option.
330
331   $bytes = zmq_send($sock, $buffer, $size, $flags)
332       Queues $size bytes from $buffer to be sent from the socket. Argument
333       $flags may be omitted. If $size is -1, then the size of the buffer
334       calculated via "SvPV()" will be used.
335
336       Returns the number of bytes sent on success (which should be exact
337       $size)
338
339       Returns -1 upon failure, and sets $!.
340
341   $rv = zmq_sendmsg($sock, $message, $flags)
342       Queues $message to be sent via $sock. Argument $flags may be omitted.
343
344       If $message is a non-ref, creates a new ZMQ::LibZMQ4::Message object
345       via "zmq_msg_init_data()", and uses that to pass to the underlying C
346       layer..
347
348       Returns the number of bytes sent on success (which should be exact
349       $size)
350
351       Returns -1 upon failure, and sets $!.
352
353       Note: Deprecated in favor of "zmq_msg_send()", and may not be available
354       depending on your libzmq version.
355
356   $rv = zmq_msg_send($message, $sock, $flags)
357       Queues $message to be sent via $sock. Argument $flags may be omitted.
358
359       If $message is a non-ref, creates a new ZMQ::LibZMQ4::Message object
360       via "zmq_msg_init_data()", and uses that to pass to the underlying C
361       layer..
362
363       Returns the number of bytes sent on success (which should be exact
364       $size)
365
366       Returns -1 upon failure, and sets $!.
367
368       Note: may not be available depending on your libzmq version.
369
370   $rv = zmq_recv($sock, $buffer, $len, $flags)
371       Receives a new message from $sock, and store the message payload in
372       $buffer, up to $len bytes. Argument $flags may be omitted.
373
374       Returns the number of bytes in the original message, which may exceed
375       $len (if you have $rv > $len, then the message was truncated).
376
377       Returns -1 upon failure, and sets $!.
378
379   $message = zmq_recvmsg($sock, $flags)
380       Receives a new message from $sock. Argument $flags may be omitted.
381       Returns the message object.
382
383       Returns undef upon failure, and sets $!.
384
385       Note: Although this function is marked as deprecated in libzmq3, it
386       will stay in the Perl binding as the official short-circuit version of
387       "zmq_msg_recv()", so that you don't have to create a message object
388       every time.
389
390   $rv = zmq_msg_recv($msg, $sock, $flags)
391       Receives a new message from $sock, and writes the new content to $msg.
392       Argument $flags may be omitted.
393
394       Returns the number of bytes in the message if successful.
395
396       Returns -1 upon failure, and sets $!.
397
398       Other than the fact that libzmq has deprecated "zmq_recvmsg()", this
399       construct is useful if you don't want to allocate a message struct for
400       every recv call:
401
402           my $msg = zmq_msg_init();
403           while (1) {
404               my $rv = zmq_msg_recv($msg, $sock, $flags);
405               ...
406           }
407
408       Note: may not be available depending on your libzmq version
409
410   $msg = zmq_msg_init()
411       Creates a new message object.
412
413       Returns undef upon failure, and sets $!.
414
415   $msg = zmq_msg_init_data($string)
416       Creates a new message object, and sets the message payload to the
417       string in $string.
418
419       Returns undef upon failure, and sets $!.
420
421   $msg = zmq_msg_init_size($size)
422       Creates a new message object, allocating $size bytes. This call isn't
423       so useful from within Perl
424
425       Returns undef upon failure, and sets $!.
426
427   $string = zmq_msg_data( $msg )
428       Returns the payload contained in $msg
429
430   $size = zmq_msg_size( $msg )
431       Returns the size of payload contained in $msg
432
433   zmq_msg_copy( $dst, $src )
434       Copies contents of $src to $dst.
435
436       Returns a non-zero status upon failure, and sets $!.
437
438   zmq_msg_move( $dst, $src )
439       Moves contents of $src to $dst
440
441       Returns a non-zero status upon failure, and sets $!.
442
443   $rv = zmq_msg_close( $msg )
444       Closes, cleans up the message.
445
446       Returns a non-zero status upon failure, and sets $!.
447
448   $rv = zmq_poll( \@pollitems, $timeout )
449       @pollitems are list of hash references containing the following
450       elements:
451
452       fd or socket
453           One of either "fd" or "socket" key must exist. "fd" should contain
454           a UNIX file descriptor. "socket" should contain a
455           "ZMQ::LibZMQ4::Socket" socket object.
456
457       events
458           A bit mask containing "ZMQ_POLLOUT", "ZMQ_POLLIN", "ZMQ_POLLERR" or
459           combination there of.
460
461       callback
462           A subroutine reference, which will be called without arguments when
463           the socket or descriptor is available.
464
465       In scalar context, returns the return value of zmq_poll() in the C
466       layer, and sets $!.
467
468           my $rv = zmq_poll( .... ); # do scalar(zmq_poll(...)) if you're nuerotic
469           if ( $rv == -1 ) {
470               warn "zmq_poll failed: $!";
471           }
472
473       In list context, return a list containing as many booleans as there are
474       elements in @pollitems.  These booleans indicate whether the socket in
475       question has fired the callback.
476
477           my @pollitems = (...);
478           my @fired     = zmq_poll( @pollitems ... );
479           for my $i ( 0 .. $#pollitems ) {
480               my $fired = $fired[$i];
481               if ( $fired ) {
482                   my $item = $pollitems[$i];
483                   ...
484               }
485           }
486
487   zmq_version()
488       Returns the version of the underlying zeromq library that is being
489       linked.  In scalar context, returns a dotted version string. In list
490       context, returns a 3-element list of the version numbers:
491
492           my $version_string = ZMQ::LibZMQ4::zmq_version();
493           my ($major, $minor, $patch) = ZMQ::LibZMQ4::zmq_version();
494
495   zmq_device($type, $sock1, $sock2)
496       Creates a new "device". See "zmq_device" for details. zmq_device() will
497       only return if/when the current context is closed. Therefore, the
498       return value is always -1, and $! is always ETERM
499
500       Note: may not be available depending on your libzmq version.
501
502   zmq_proxy($frontend_sock, $backend_sock, $capture_sock)
503       WARNING: EXPERIMENTAL. Use at your own risk.
504
505       Start a proxy in the current thread, which connects the frontend socket
506       to a backend socket. The capture sock is optional, and is by default
507       undef.
508
509       Note: may not be available depending on your libzmq version.
510
511   $rv = zmq_socket_monitor($socket, $addr, events)
512       Note: may not be available depending on your libzmq version.
513

FUNCTIONS PROVIDED BY ZMQ::LIBZMQ4

515       These functions are provided by ZMQ::LibZMQ4 to make some operations
516       easier in the Perl binding. They are not part of the official libzmq
517       interface.
518
519   $value = zmq_getsockopt_int( $sock, $option )
520   $value = zmq_getsockopt_int64( $sock, $option )
521   $value = zmq_getsockopt_string( $sock, $option )
522   $value = zmq_getsockopt_uint64( $sock, $option )
523   $rv = zmq_setsockopt_int( $sock, $option, $value );
524   $rv = zmq_setsockopt_int64( $sock, $option, $value );
525   $rv = zmq_setsockopt_string( $sock, $option, $value );
526   $rv = zmq_setsockopt_uint64( $sock, $option, $value );

DEBUGGING XS

528       If you see segmentation faults, and such, you need to figure out where
529       the error is occurring in order for the maintainers to figure out what
530       happened. Here's a very very brief explanation of steps involved.
531
532       First, make sure to compile "ZMQ::LibZMQ4" with debugging on by
533       specifying -g:
534
535           perl Makefile.PL -g
536           make
537
538       Then fire gdb:
539
540           gdb perl
541           (gdb) R -Mblib /path/to/your/script.pl
542
543       When you see the crash, get a backtrace:
544
545           (gdb) bt
546

CAVEATS

548       This is an early release. Proceed with caution, please report (or
549       better yet: fix) bugs you encounter.
550
551       This module has been tested against zeromq 3.2.2. Semantics of this
552       module rely heavily on the underlying zeromq version. Make sure you
553       know which version of zeromq you're working with.
554
555       As of 1.04 some new constants have been added, but they are not really
556       meant to be used by consumers of this module. If you find yourself
557       looking at these, please let us know why you need to use it -- we'll
558       see if we can find a workaround, or make these constants public.
559

AUTHOR

574       Rodrigo Mosconi "<perl@mosconi.mat.br>"
575

COPYRIGHT AND LICENSE

577       The ZMQ::LibZMQ4 module is
578
579       Copyright (C) 2014 by Rodrigo Mosconi
580
581       This library is free software; you can redistribute it and/or modify it
582       under the same terms as Perl itself, either Perl version 5.8.0 or, at
583       your option, any later version of Perl 5 you may have available.
584
585
586
587perl v5.32.0                      2020-07-28                   ZMQ::LibZMQ4(3)