About pzmq:

ZeroMQ 3.2+ bindings.

Consult official C API reference first.





Contents

Top-level API

Macro with-socket (name-and-context type-and-options &body body)
Arguments:
  • name-and-context -- name | (name context)
  • type-and-options -- type | (type :option1 value1 :option2 value2 ...)
Details:
Initialize and close ZMQ socket around body. Type is one of the types acceptedby SOCKET. Options are passed to SETSOCKOPT one by one.

When TYPE is :SUB, and :SUBSCRIBE is not given in OPTIONS, imply subscribe to all. If this is undesirable, provide :SUBSCRIBE NIL.

When context is not specified, it either comes from surrounding WITH-CONTEXTor WITH-SOCKET in *DEFAULT-CONTEXT*, or is established by thisWITH-SOCKET and stored in *DEFAULT-CONTEXT* for the timespan of this block.
See also:

Macro with-sockets ((&rest socket-definitions) &body body)
Details:
Nest multiple sockets.

Function bind (socket endpoint)
Arguments:
  • endpoint -- "transport://address"
Details:
Accept connections on a socket.

Only one socket may be bound to a particular endpoint. Bound socket may receive messages sent before it was bound.

Function connect (socket endpoint)
Arguments:
  • endpoint -- "transport://address"
Details:
Connect a socket.

Many sockets may connect to the same endpoint. Connected socket may not receive messages sent before it was bound.

Function recv-string (socket &key dontwait (encoding *default-foreign-encoding*))
Details:
Receive a message part from a socket as a string.

Function send (socket buf &key len dontwait sndmore (encoding *default-foreign-encoding*))
Arguments:
  • buf -- string, or foreign byte array
  • len -- ignored, or array size
Details:
Send a message part on a socket.


Macro with-poll-items (name (&rest items) &body body)
Arguments:
  • items -- (item ...)
  • item -- name | (name [:pollin] [:pollout])
Details:
Prepare POLLITEM array in NAME.

Without parentheses, an item indicates subscription to both :pollin and :pollout.

Function poll (items &optional (timeout -1))
Arguments:
  • items -- Poll items prepared with WITH-POLL-ITEMS
  • timeout -- -1 : wait indefinitely; N : wait N milliseconds
Returns:
The number of ready items.
Details:
Input/output multiplexing on ZeroMQ sockets.
See also:

Function revents (items subscript)
Returns:
([:pollin] [:pollout])
Details:
Return a list of events - :pollin, :pollout or both - that happened to an indicated item, counting from 0.

Middle-level API

Macro with-context (name-and-options &body body)
Arguments:
  • name-and-options -- name | (name options)
  • name -- name | NIL
  • options -- :io-threads INT :max-sockets INT; as per CTX-SET
Details:
Initialize and destroy ZMQ context around body.

Use NIL for anonymous context, stored in *DEFAULT-CONTEXT*.

Omit WITH-CONTEXT altogether, and WITH-SOCKET will establish it by itself.

Note: unwind-protected CTX-DESTROY will not return until all governed sockets have sent all queued messages, unless they limited their wait time with :LINGER socket parameter.
See also:

Macro with-message (name &body body)
Details:
Initialize and free ZMQ message around body.

Low-level API

Function ctx-new ()
Details:
Create new ØMQ context.
See also:

Function ctx-set (context &key (io-threads 1 io-threads-p) (max-sockets 1024 max-sockets-p))
Details:
Set context options.

Function ctx-get (context option-name)
Arguments:
  • option-name -- :io-threads | :max-threads
Returns:
integer
Details:
Get context options.
See also:

Function ctx-destroy (context)
Details:
Destroy a ØMQ context.

Function strerror (&optional (errnum (errno)))
Details:
Get ØMQ error message string.

Function version ()
Returns:
(major minor patch)
Details:


Report ØMQ library version.

Other

Other functions in pzmq

Function close (socket)
Details:
Close ØMQ socket.

Function device (device frontend backend)
Arguments:
  • device -- :streamer | :forwarder | :queue
  • frontend, backend -- socket
Details:
Start built-in ØMQ device in the calling thread. Never returns unless interrupted.

Function errno ()
Details:
Retrieve value of errno for the calling thread.
See also:

Function getsockopt (socket option-name)
Arguments:
  • option-name -- keyword
Returns:
integer, or string for :identity and :last-endpoint
Details:
Get ØMQ socket options.

Function msg-close (msg)
Details:
Release ØMQ message.

Low-level API. Consider using WITH-MESSAGE.
See also:

Function msg-copy (dest src)
Details:
Copy content of a message to another message.

Function msg-data (msg)
Details:
Retrieve pointer to message content.

Function msg-get (msg property)
Arguments:
  • property -- :more
Details:
Get message property. The only defined property is :more; equivalent to MSG-MORE.
See also:

Function msg-init (msg)
Details:
Initialise empty ØMQ message.

Low-level API. Consider using WITH-MESSAGE.
See also:

Function msg-init-data (msg data)
Details:
Initialise ØMQ message from a supplied buffer.
See also:

Function msg-init-size (msg size)
Details:
Initialise ØMQ message of a specified size.
See also:

Function msg-more (msg)
Details:
Indicate if there are more message parts to receive.

Function msg-move (dest src)
Details:
Move content of a message to another message.

Function msg-recv (msg socket &key dontwait)
Details:
Receive a message part from a socket.

Function msg-send (msg socket &key dontwait sndmore)
Details:
Send a message part on a socket.

Function msg-set (msg property value)
Details:
Set message property. No setable properties defined yet.

Function msg-size (msg)
Details:
Retrieve message content size in bytes.

Function setsockopt (socket option-name option-value)
Details:
Set ØMQ socket options.

Function socket (context type)
Arguments:
  • type -- :pair | :pub | :sub | :req | :rep | :dealer | :router | :pull | :push | :xpub | :xsub
Details:
Create ØMQ socket.

Other macros in pzmq

Macro with-context (name-and-options &body body)
Arguments:
  • name-and-options -- name | (name options)
  • name -- name | NIL
  • options -- :io-threads INT :max-sockets INT; as per CTX-SET
Details:
Initialize and destroy ZMQ context around body.

Use NIL for anonymous context, stored in *DEFAULT-CONTEXT*.

Omit WITH-CONTEXT altogether, and WITH-SOCKET will establish it by itself.

Note: unwind-protected CTX-DESTROY will not return until all governed sockets have sent all queued messages, unless they limited their wait time with :LINGER socket parameter.
See also:

Macro with-message (name &body body)
Details:
Initialize and free ZMQ message around body.

Macro with-poll-items (name (&rest items) &body body)
Arguments:
  • items -- (item ...)
  • item -- name | (name [:pollin] [:pollout])
Details:
Prepare POLLITEM array in NAME.

Without parentheses, an item indicates subscription to both :pollin and :pollout.

Macro with-socket (name-and-context type-and-options &body body)
Arguments:
  • name-and-context -- name | (name context)
  • type-and-options -- type | (type :option1 value1 :option2 value2 ...)
Details:
Initialize and close ZMQ socket around body. Type is one of the types acceptedby SOCKET. Options are passed to SETSOCKOPT one by one.

When TYPE is :SUB, and :SUBSCRIBE is not given in OPTIONS, imply subscribe to all. If this is undesirable, provide :SUBSCRIBE NIL.

When context is not specified, it either comes from surrounding WITH-CONTEXTor WITH-SOCKET in *DEFAULT-CONTEXT*, or is established by thisWITH-SOCKET and stored in *DEFAULT-CONTEXT* for the timespan of this block.
See also:

Macro with-sockets ((&rest socket-definitions) &body body)
Details:
Nest multiple sockets.

Other classes in pzmq

Class c-error
Superclasses:
common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
libzmq-error

No documentation string. Possibly unimplemented or incomplete.


Class eaddrinuse
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class eaddrnotavail
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class eagain
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class efault
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class efsm
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class eintr
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class einval
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class emfile
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class emthread
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class enocompatprot
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class enodev
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class enomem
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class enotsock
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class enotsup
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class eprotonosuppo
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class eterm
Superclasses:
libzmq-error, c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
None

No documentation string. Possibly unimplemented or incomplete.


Class libzmq-error
Superclasses:
c-error, common-lisp:error, common-lisp:serious-condition, common-lisp:condition, sb-pcl::slot-object, common-lisp:t
Documented Subclasses:
eaddrinuse, eaddrnotavail, eagain, efault, efsm, eintr, einval, emfile, emthread, enocompatprot, enodev, enomem, enotsock, enotsup, eprotonosuppo, eterm

No documentation string. Possibly unimplemented or incomplete.


Other variables in pzmq

Variable *default-context*
Details:
Implicit context from WITH-CONTEXT for WITH-SOCKET.
See also:

Variable *restart-interrupted-calls*
Details:
When blocking ZMQ call returns with EINTR automatically retry it, instead of signaling a condition.

Explanation: Every time garbage collection happens in implementation that use signals to stop threads (like SBCL), every ZMQ blocking ZMQ call, will error out with EINTR on every GC.

When this variable is non-NIL, PZMQ will retry the call, as if you had selected CONTINUE restart.

Note that EINTR will also be returned by any other interruptions such as attaching a debugger to a thread, or pressing Ctrl-C.

If you would like to terminate your ZMQ call in these cases, then rebind *RESTART-INTERRUPTED-CALLS*, and have a HANDLER-BIND set it to NIL on these special cases.

Then at a lower level, ignore EINTR errors. It is important to use HANDLER-BIND and not HANDLER-CASE, because we want the ZMQ function being interrupted to return EINTR, performing any necessary cleanups, using HANDLER-CASE or using non-local exit from HANDLER-BIND will accomplish its task, but without letting ZMQ call properly cleanupafter itself.

Index of exported symbols

pzmq:*default-context*, variable
pzmq:*restart-interrupted-calls*, variable
pzmq:bind, function
pzmq:c-error, class  (undocumented)
pzmq:close, function
pzmq:connect, function
pzmq:ctx-destroy, function
pzmq:ctx-get, function
pzmq:ctx-new, function
pzmq:ctx-set, function
pzmq:device, function
pzmq:eaddrinuse, class  (undocumented)
pzmq:eaddrnotavail, class  (undocumented)
pzmq:eagain, class  (undocumented)
pzmq:efault, class  (undocumented)
pzmq:efsm, class  (undocumented)
pzmq:eintr, class  (undocumented)
pzmq:einval, class  (undocumented)
pzmq:emfile, class  (undocumented)
pzmq:emthread, class  (undocumented)
pzmq:enocompatprot, class  (undocumented)
pzmq:enodev, class  (undocumented)
pzmq:enomem, class  (undocumented)
pzmq:enotsock, class  (undocumented)
pzmq:enotsup, class  (undocumented)
pzmq:eprotonosuppo, class  (undocumented)
pzmq:errno, function
pzmq:eterm, class  (undocumented)
pzmq:getsockopt, function
pzmq:libzmq-error, class  (undocumented)
pzmq:msg-close, function
pzmq:msg-copy, function
pzmq:msg-data, function
pzmq:msg-get, function
pzmq:msg-init, function
pzmq:msg-init-data, function
pzmq:msg-init-size, function
pzmq:msg-more, function
pzmq:msg-move, function
pzmq:msg-recv, function
pzmq:msg-send, function
pzmq:msg-set, function
pzmq:msg-size, function
pzmq:poll, function
pzmq:recv-string, function
pzmq:revents, function
pzmq:send, function
pzmq:setsockopt, function
pzmq:socket, function
pzmq:strerror, function
pzmq:version, function
pzmq:with-context, macro
pzmq:with-message, macro
pzmq:with-poll-items, macro
pzmq:with-socket, macro
pzmq:with-sockets, macro