About pzmq:
Contents
- Package pzmq
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.
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.
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.
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*))
Returns:
A string.
Details:
Receive a message part from a socket as a string.
Function recv-octets (socket &key dontwait)
Returns:
A (vector (unsigned-byte 8)).
Details:
Receive a message part from a socket as an octet vector.
Function send (socket buf &key len dontwait sndmore (encoding *default-foreign-encoding*))
Arguments:
- buf -- string, or foreign byte array, or byte array, or nil for an empty message
- 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.
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.
Function curve-keypair ()
Returns:
The public key as the primary value and the secret key as the secondaryvalue; both of type (VECTOR (UNSIGNED-BYTE 8) 32).
Details:
Generates and returns a CurveZMQ keypair.
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 terminate 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-TERM will not return until all governed sockets have sent all queued messages, unless they limited their wait time with :LINGER socket parameter.
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-TERM 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 ()
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)
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 ctx-shutdown (context)
Function ctx-term (context)
Details:
Destroy a ØMQ context.
Function device (device frontend backend)
Function errno ()
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)
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)
Function msg-init (msg)
Details:
See also:
Function msg-init-data (msg data)
Function msg-init-size (msg size)
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 proxy (frontend backend capture)
Arguments:
- frontend, backend, capture -- socket
Details:
Start built-in ØMQ proxy in the current application thread.
Function setsockopt (socket option-name option-value)
Details:
Set ØMQ socket options.
Boolean options accept generalized Lisp booleans.Binary options are supported either as strings or UB8 vectors.
Function socket (context type)
Arguments:
- type -- :pair | :pub | :sub | :req | :rep | :dealer | :router | :pull | :push | :xpub | :xsub | :stream
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 terminate 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-TERM will not return until all governed sockets have sent all queued messages, unless they limited their wait time with :LINGER socket parameter.
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-TERM 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-messages ((&rest names) &body body)
No documentation string. Possibly unimplemented or incomplete.
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.
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.
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:
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 ehostunreach
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 enocompatproto
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 enoent
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 eprotonosupport
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, ehostunreach, eintr, einval, emfile, emthread, enocompatproto, enodev, enoent, enomem, enotsock, enotsup, eprotonosupport, eterm
No documentation string. Possibly unimplemented or incomplete.
Other variables in pzmq
Variable *default-context*
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.
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: | ctx-shutdown, function |
| pzmq: | ctx-term, function |
| pzmq: | curve-keypair, 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: | ehostunreach, class (undocumented) |
| pzmq: | eintr, class (undocumented) |
| pzmq: | einval, class (undocumented) |
| pzmq: | emfile, class (undocumented) |
| pzmq: | emthread, class (undocumented) |
| pzmq: | enocompatproto, class (undocumented) |
| pzmq: | enodev, class (undocumented) |
| pzmq: | enoent, class (undocumented) |
| pzmq: | enomem, class (undocumented) |
| pzmq: | enotsock, class (undocumented) |
| pzmq: | enotsup, class (undocumented) |
| pzmq: | eprotonosupport, 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: | proxy, function |
| pzmq: | recv-octets, 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-messages, macro (undocumented) |
| pzmq: | with-poll-items, macro |
| pzmq: | with-socket, macro |
| pzmq: | with-sockets, macro |