zmq_cl(7) man page added

man/man7/zmq_cl.7

@@ -2,8 +2,123 @@
 .SH NAME
 Common Lisp API for 0MQ lightweight messaging kernel
 .SH SYNOPSIS
-.SH DESCRIPTION
-.SH "SEE ALSO"
-.SH AUTHOR
-Martin Sustrik <sustrik at 250bpm dot com>
 
+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>