mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-13 10:52:56 +01:00
125 lines
3.2 KiB
Groff
125 lines
3.2 KiB
Groff
.TH zmq_cl 7 "" "(c)2007-2010 iMatix Corporation" "0MQ User Manuals"
|
|
.SH NAME
|
|
Common Lisp API for 0MQ lightweight messaging kernel
|
|
.SH SYNOPSIS
|
|
|
|
This manual page explains how Common Lisp API maps to underlying C
|
|
API.
|
|
|
|
Common Lisp API repeats C API in general. All constants defined with C
|
|
API are available with Common Lisp API. C names are mapped to lisp
|
|
names by these rules: a) all names are `zmq' namespace; b) all names
|
|
are in lower case; c) underscores translate to dashes.
|
|
|
|
Example of mappings:
|
|
|
|
.IR zmq_msg_init_data
|
|
maps to
|
|
.IR zmq:msg-init-data
|
|
|
|
.IR ZMQ_PUB
|
|
maps to
|
|
.IR zmq:pub
|
|
|
|
To learn about individual functions and parameters check
|
|
appropriate C API manual pages.
|
|
|
|
For example, to understand
|
|
.IR zmq:setsockopt
|
|
function check
|
|
.BR zmq_setsockopt(3) .
|
|
|
|
.SH Data structures
|
|
Data structures are wrapped into CLOS classes with automatic memory
|
|
management. 0MQ describes two such structures:
|
|
.IR msg_t
|
|
and
|
|
.IR pollitem_t .
|
|
|
|
Message constructor supports keywords
|
|
.IR :size
|
|
and
|
|
.IR :data.
|
|
Keyword :size specifies the size of
|
|
message. Keyword :data specifies initial contents of message, and it
|
|
can be either string or 8-bit array. For example:
|
|
|
|
* (make-instance 'zmq:msg :data #(1 2 3))
|
|
|
|
creates a message with 3 bytes '1, 2, 3' in it.
|
|
|
|
.SH Accessing message data
|
|
|
|
There 3 functions to read message body in different forms:
|
|
msg-data-as-string, msg-data-as-array and msg-data-as-is, returning
|
|
data as string, as array and as raw foreign pointer to underlaying
|
|
buffer respectively. For example:
|
|
|
|
* (zmq:msg-data-as-array msg)
|
|
|
|
returns #(1 2 3) for message from previous example.
|
|
|
|
It is possible to access underlying foreign object via class slot
|
|
named `raw'.
|
|
|
|
* (slot-value obj 'zmq:raw)
|
|
|
|
or, if `obj' is of known type `msg':
|
|
|
|
* (zmq:msg-raw obj)
|
|
|
|
.SH Macros
|
|
There are several macroses to help with managing zeromq objects:
|
|
|
|
.SH with-context
|
|
Macro
|
|
.IR with-context
|
|
creates 0MQ context and requires 3 obligatory arguments: context name,
|
|
number of application threads and number of input/output
|
|
threads. Optional parameter `flags' can be also supplied, see
|
|
.BR zmq_init(3) .
|
|
Context is terminated implicitly at the end of macro block.
|
|
|
|
.SH with-socket
|
|
Macro
|
|
.IR with-socket
|
|
creates 0MQ socket within given context. Requires 3 arguments: socket
|
|
name, context name and socket type. See
|
|
.BR zmq_socket(3) .
|
|
Socket is closed implicitly at the end of macro block.
|
|
|
|
.SH with-polls
|
|
Macro
|
|
.IR with-polls
|
|
creates 0MQ polls, containing different sets of pollitems. For
|
|
example, to create two poll sets for network pipes:
|
|
|
|
* (zmq:with-polls ((poll1 . ((sock1 . zmq:pollin)
|
|
(sock2 . zmq:pollout)))
|
|
(poll2 . ((sock1 . zmq:pollout)
|
|
(sock2 . zmq:pollin))))
|
|
|
|
(process-sockets (zmq:poll poll-set1))
|
|
|
|
(process-sockets (zmq:poll poll-set2)))
|
|
|
|
Note,
|
|
.IR zmq:poll
|
|
returns list of revents for sockets from given poll set.
|
|
|
|
Polls are closed implicitly at the end of macro block.
|
|
|
|
.SH EXAMPLE
|
|
.nf
|
|
|
|
(zmq::with-context (ctx 1 1)
|
|
(zmq:with-socket (s ctx zmq:pub)
|
|
(zmq:connect s "tcp://192.168.0.115:5555")
|
|
(zmq:send s (make-instance 'zmq:msg :data "Hello, world!"))))
|
|
|
|
.SH "SEE ALSO"
|
|
.BR zmq(7)
|
|
.SH AUTHOR
|
|
Martin Sustrik <sustrik at 250bpm dot com>,
|
|
Vitaly Mayatskikh <v dot mayatskih at gmail dot com>
|