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