chickadee » zmq

zmq

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

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/zmq

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

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

zmq-versionprocedure

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

Contexts

zmq-default-context #!optional contextparameter

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.

zmq-io-threads #!optional numberparameter

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

make-context numberprocedure

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

context? contextprocedure

Check whether context is a ZeroMQ context.

Sockets

make-socket type #!optional contextprocedure

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.

socket? socketprocedure

Check whether socket is a ZeroMQ socket.

close-socket socketprocedure

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.

bind-socket socket endpointprocedure

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

connect-socket socket endpointprocedure

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

socket-option-set! socket option valueprocedure

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

sndhwm

high water mark (integer, maximum number of outstanding messages)

rcvhwm

high water mark (integer, maximum number of outstanding messages)

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)

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.

socket-option socket optionprocedure

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.

socket-fd socketprocedure

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

send-message socket message #!key non-blocking send-moreprocedure

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).

receive-message socket #!key non-blocking asprocedure

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).

receive-message* socket #!key asprocedure

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

make-poll-item socket/fd #!key in outprocedure

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.

poll-item-fd itemprocedure

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

poll-item-socket itemprocedure

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

poll-item-in? itemprocedure

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

poll-item-out? itemprocedure

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

poll-item-error? itemprocedure

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

poll poll-items timeout/blockprocedure

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