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.
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.
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.
Currently, the zmq egg provides bindings for interacting with ZeroMQ contexts, sockets, messages and poll-items.
- (zmq-version) procedure
Returns the ZeroMQ version as a list of the form (major minor patch).
- (zmq-default-context [context]) parameter
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 [number]) parameter
number of I/O threads to use for the zmq-default-context. Default: 1.
- (make-context number) procedure
Creates a new ZeroMQ context using number I/O threads.
- (context? context) procedure
Check whether context is a ZeroMQ context.
- (make-socket type [context]) procedure
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? socket) procedure
Check whether socket is a ZeroMQ socket.
- (close-socket socket) procedure
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 endpoint) procedure
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 endpoint) procedure
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 value) procedure
Destructively set option (a symbol) of socket to value (type depending on the respective option). The following options are available:
- high water mark (integer, maximum number of outstanding messages)
- disk offload size (integer, bytes)
- I/O thread affinity (integer, bitmap)
- socket identity (string, max. 255 bytes)
- add message filter (string, message prefix)
- remove message filter (string, message prefix)
- multicast data rate (integer, kilobits per second)
- multicast recovery interval (integer, seconds)
- multicast loopback (boolean)
- kernel transmit buffer size (integer, bytes, 0 for OS default)
- 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 option) procedure
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 socket) procedure
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.
- (send-message socket message #!key non-blocking send-more) procedure
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 as) procedure
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 as) procedure
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.
- (make-poll-item socket/fd #!key in out) procedure
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 item) procedure
Return item's POSIX file descriptor if is has been created with one (see make-poll-item).
- (poll-item-socket item) procedure
Return item's socket if is has been created with one (see make-poll-item).
- (poll-item-in? item) procedure
Check whether item's socket or file descriptor is ready for reading.
- (poll-item-out? item) procedure
Check whether item's socket or file descriptor is ready for writing.
- (poll-item-error? item) procedure
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/block) procedure
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.
- deprecate message-* procedures and message record type.
- add receive-message* for better blocking reads
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