Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

zmq
  1. Outdated egg!
  2. zmq
    1. WARNING
    2. Description
    3. Author
    4. Requirements
    5. Documentation
      1. General
      2. Contexts
      3. Sockets
      4. Communication
      5. Polling
    6. Changelog
    7. License

WARNING

This egg is currently unmaintained and has some known problems. Also, it doesn't support more recent libzmq releases. You may want to look at the nanomsg egg instead.

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.

Author

Moritz Heidkamp

Requirements

You only need to have the foreigners egg as well as libzmq including its header files installed. Note that at least version 2.2 of ZeroMQ is required, which is a stable release from 2012-04-04. Version 3.x and up are not supported.

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 descriptor is edge-triggered.

Communication

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

Send message via socket with message being a string or a blob. If non-blocking is #t, the function call will not block (default: #f). If send-more is #t, 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 as)

Receive the next message from socket. By default, the message data is returned as a string. This can be changed using the as argument. It can either be string, blob or a procedure. The latter will be called with a data pointer and an integer (the number of bytes). The value returned by the procedure will be the return value of receive-message and should make sure to read the message data. If non-blocking is #t, the function call will not block and return #f if no message is available (default: #f).

[procedure] (receive-message* socket #!key as)

Receive the next message from socket. The as argument works the same way as receive-message's does. This procedure will read blockingly but only block the current thread instead of the whole process. Also, it will allow signals to be handled immediately and is thus the recomended way for reading messages blockingly even for single-threaded programs. This procedure has been added in version 0.1.1.

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.

Changelog
0.1.0
deprecate message-* procedures and message record type.
0.1.1
add receive-message* for better blocking reads

License

 
 Copyright (C) 2010-2012 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