1ZMQ::LibZMQ4(3) User Contributed Perl Documentation ZMQ::LibZMQ4(3)
2
3
4
6 ZMQ::LibZMQ4 - A libzmq 4.x wrapper for Perl
7
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
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
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
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
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
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
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
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
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 );
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
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
561 <http://zeromq.org>
562
563 <http://github.com/mosconi/p5-ZMQ>
564
565 <http://github.com/lestrrat/p5-ZMQ>
566
567 ZMQ::Constants
568
569 ZMQ::LibZMQ3
570
571 ZMQ::LibZMQ2
572
574 Rodrigo Mosconi "<perl@mosconi.mat.br>"
575
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.30.0 2019-07-26 ZMQ::LibZMQ4(3)