summaryrefslogtreecommitdiff
path: root/man/man7/zmq_cl.7
blob: b9dd14fb68ba784b51a89ca6f595b6ac6dc5c272 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
.TH zmq_cl 7 "" "(c)2007-2009 FastMQ Inc." "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>