zmq (historical revision 21223) - The CHICKEN Scheme wiki

You are looking at historical revision 21223 of this page. It may differ significantly from its current revision.

zmq

zmq
1. Description
2. Author
3. Requirements
4. Documentation
  1. General
  2. Contexts
  3. Sockets
  4. Messages
  5. Communication
  6. Polling
5. License

Description

Bindings for the ZeroMQ (aka ZMQ, ØMQ or 0MQ) API. To get an idea of what ZeroMQ is and how it can be used, read the ZeroMQ Guide.

The binding is currently fairly low-level as it mostly directly maps to the C API with only a few abstractions to make it more Scheme-like. More of those will follow in future versions.

Requirements

You only need to have the foreigners egg as well as libzmq including its header files installed.

Documentation

Currently, the zmq egg provides bindings for interacting with ZeroMQ contexts, sockets, messages and poll-items.

General

[procedure] (zmq-version)

Returns the ZeroMQ version as a list of the form (major minor patch).

Contexts

[parameter] (zmq-default-context [context])

The ZeroMQ context used by all make-socket calls as the default context argument. Usually, you only need one context per application (unless you know what you need more than one for). Note that this parameter is initialized lazily upon the first call to make-socket. See also: zmq-io-threads.

[parameter] (zmq-io-threads [number])

number of I/O threads to use for the zmq-default-context. Default: 1.

[procedure] (make-context number)

Creates a new ZeroMQ context using number I/O threads.

[procedure] (context? context)

Check whether context is a ZeroMQ context.

Sockets

[procedure] (make-socket type [context])

Create a ZeroMQ socket of type, which must be one of the symbols pull, push, pair, pub, sub, req, rep, xreq or xrep. See the zmq_socket documentation for information about what the different types mean. context must be a ZeroMQ context and is zmq-default-context by default.

[procedure] (socket? socket)

Check whether socket is a ZeroMQ socket.

[procedure] (close-socket socket)

Close the ZeroMQ socket. This is usually done by the finalizer so you only have to call this if you want to close a socket early for whatever reason.

[procedure] (bind-socket socket endpoint)

Bind socket to endpoint which must be given as a string of the format transport://address (for details, see the documentation for zmq_bind).

[procedure] (connect-socket socket endpoint)

Connect socket to endpoint which is given as a string of the format transport://address (for details, see the documentation for zmq_connect).

[procedure] (socket-option-set! socket option value)

Destructively set option (a symbol) of socket to value (type depending on the respective option). The following options are available:

hwm: high water mark (integer, maximum number of outstanding messages)
swap: disk offload size (integer, bytes)
affinity: I/O thread affinity (integer, bitmap)
identity: socket identity (string, max. 255 bytes)
subscribe: add message filter (string, message prefix)
unsubscribe: remove message filter (string, message prefix)
rate: multicast data rate (integer, kilobits per second)
recovery-ivl: multicast recovery interval (integer, seconds)
mcast-loop: multicast loopback (boolean)
sndbuf: kernel transmit buffer size (integer, bytes, 0 for OS default)
rcvbuf: kernel receive buffer size (integer, bytes, 0 for OS default)

For more detailed descriptions of the options, see the documentation for zmq_setsockopt.

[procedure] (socket-option socket option)

Retrieve socket's current option value. option must be given as one the symbols hwm, swap, affinity, rate, recovery-ivl, sndbuf, rcvbuf, rcvmore, mcast-loop or identity. For descriptions of the individual options see the documentation for zmq_getsockopt.

[procedure] (socket-fd socket)

Retrieve the socket's file descriptor which can be used for traditional polling purposes. It is especially useful in conjunction with Chicken's SRFI-18 extension thread-wait-for-i/o! to be able to idly wait for messages in a separate thread. Note that the file cdescriptor is edge-triggered.

Messages

[procedure] (make-message [data-or-size])

If the optional argument data-or-size is not given (or #f), create an empty message. If a string is given, use it as the message's payload. If an integer is given, allocate a message of that many bytes.

[procedure] (message? message)

Check whether message is a ZeroMQ message record.

[procedure] (message-size message)

Retrieve message's size in bytes.

[procedure] (message->string message)

Retrieve message's payload as a string.

[procedure] (copy-message message)

Rteurn a copy of message. Note that this actually copies message's data, i.e. it doesn't bind the API call zmq_msg_copy.

Communication

[procedure] (send-message socket message #!key non-blocking send-more)

Send message via socket with message being either a message record or a string. If non-blocking is not #f, the function call will not block (default: #f). If send-more is not #f, mark this message as part of a multi-part messaging and that further parts are to follow (see the documentation about multi-part messages for more information, default: #f).

[procedure] (receive-message socket #!key non-blocking)

Receive the next message from socket. If non-blocking if not #f, the function call will not block and return #f if no message is available (default: #f).

Polling

[procedure] (make-poll-item socket/fd #!key in out)

Create a ZeroMQ poll-item for socket/fd which can either be a ZeroMQ socket or a POSIX file descriptor. The keyword arguments in and out are booleans indicating whether the item should poll for incoming or outgoing data. Both are #f by default so make sure to pass at least one as #t.

[procedure] (poll-item-fd item)

Return item's POSIX file descriptor if is has been created with one (see make-poll-item).

[procedure] (poll-item-socket item)

Return item's socket if is has been created with one (see make-poll-item).

[procedure] (poll-item-in? item)

Check whether item's socket or file descriptor is ready for reading.

[procedure] (poll-item-out? item)

Check whether item's socket or file descriptor is ready for writing.

[procedure] (poll-item-error? item)

Check whether there is an error condition present on item's file descriptor. This will never be the case for ZeroMQ sockets.

[procedure] (poll poll-items timeout/block)

Poll the poll-item list poll-items for activity. timeout/block can either be #t which will block until one of the poll-items is ready. When #f is passed the call will not block and return #f when no poll-item is ready. Alternatively, an integer may be passed, indicating the number of microseconds to wait for activity.

The return value is a number indicating how many poll-items are ready.

License

 Copyright (C) 2010 Moritz Heidkamp
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.
 
 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.
 
 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

zmq