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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
/*
Copyright (c) 2007-2009 FastMQ Inc.
This file is part of 0MQ.
0MQ is free software; you can redistribute it and/or modify it under
the terms of the Lesser GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
0MQ 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
Lesser GNU General Public License for more details.
You should have received a copy of the Lesser GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef __ZMQ_H_INCLUDED__
#define __ZMQ_H_INCLUDED__
#ifdef __cplusplus
extern "C" {
#endif
#include <stddef.h>
#include <stdint.h>
#if defined MSC_VER && defined ZMQ_BUILDING_LIBZMQ
#define ZMQ_EXPORT __declspec(dllexport)
#else
#define ZMQ_EXPORT
#endif
// Maximal size of "Very Small Message". VSMs are passed by value
// to avoid excessive memory allocation/deallocation.
#define ZMQ_MAX_VSM_SIZE 30
// Message & notification types.
#define ZMQ_GAP 1
#define ZMQ_DELIMITER 31
#define ZMQ_VSM 32
// The operation should be performed in non-blocking mode. I.e. if it cannot
// be processed immediately, error should be returned with errno set to EAGAIN.
#define ZMQ_NOBLOCK 1
// zmq_send should not flush the message downstream immediately. Instead, it
// should batch ZMQ_NOFLUSH messages and send them downstream only if zmq_flush
// is invoked. This is an optimisation for cases where several messages are
// sent in a single business transaction. However, the effect is measurable
// only in extremely high-perf scenarios (million messages a second or so).
// If that's not your case, use standard flushing send instead. See exchange
// example for illustration of ZMQ_NOFLUSH functionality.
#define ZMQ_NOFLUSH 2
// Socket to communicate with a single peer. Allows for a singe connect or a
// single accept. There's no message routing or message filtering involved.
#define ZMQ_P2P 0
// Socket to distribute data. Recv fuction is not implemeted for this socket
// type. Messages are distributed in fanout fashion to all peers.
#define ZMQ_PUB 1
// Socket to subscribe to distributed data. Send function is not implemented
// for this socket type. However, subscribe function can be used to modify the
// message filter.
#define ZMQ_SUB 2
// Socket to send requests on and receive replies from. Requests are
// load-balanced among all the peers. This socket type doesn't allow for more
// recv's that there were send's.
#define ZMQ_REQ 3
// Socket to receive requests from and send replies to. This socket type allows
// only an alternated sequence of recv's and send's. Each send is routed to
// the peer that the previous recv delivered message from.
#define ZMQ_REP 4
// Prototype for the message body deallocation functions.
// It is deliberately defined in the way to comply with standard C free.
typedef void (zmq_free_fn) (void *data);
// A message. If 'shared' is true, message content pointed to by 'content'
// is shared, i.e. reference counting is used to manage its lifetime
// rather than straighforward malloc/free. struct zmq_msg_content is
// not declared in the API.
struct zmq_msg
{
struct zmq_msg_content *content;
unsigned char shared;
uint16_t vsm_size;
unsigned char vsm_data [ZMQ_MAX_VSM_SIZE];
};
// TODO: Different options...
struct zmq_opts
{
uint64_t hwm;
uint64_t lwm;
uint64_t swap;
uint64_t mask;
uint64_t taskset;
const char *identity;
const char *args;
};
// Initialise an empty message (zero bytes long).
ZMQ_EXPORT int zmq_msg_init (zmq_msg *msg);
// Initialise a message 'size' bytes long.
//
// Errors: ENOMEM - the size is too large to allocate.
ZMQ_EXPORT int zmq_msg_init_size (zmq_msg *msg, size_t size);
// Initialise a message from an existing buffer. Message isn't copied,
// instead 0SOCKETS infrastructure take ownership of the buffer and call
// deallocation functio (ffn) once it's not needed anymore.
ZMQ_EXPORT int zmq_msg_init_data (zmq_msg *msg, void *data, size_t size,
zmq_free_fn *ffn);
// Deallocate the message.
ZMQ_EXPORT int zmq_msg_close (zmq_msg *msg);
// Move the content of the message from 'src' to 'dest'. The content isn't
// copied, just moved. 'src' is an empty message after the call. Original
// content of 'dest' message is deallocated.
ZMQ_EXPORT int zmq_msg_move (zmq_msg *dest, zmq_msg *src);
// Copy the 'src' message to 'dest'. The content isn't copied, instead
// reference count is increased. Don't modify the message data after the
// call as they are shared between two messages. Original content of 'dest'
// message is deallocated.
ZMQ_EXPORT int zmq_msg_copy (zmq_msg *dest, zmq_msg *src);
// Returns pointer to message data.
ZMQ_EXPORT void *zmq_msg_data (zmq_msg *msg);
// Return size of message data (in bytes).
ZMQ_EXPORT size_t zmq_msg_size (zmq_msg *msg);
// Returns type of the message.
ZMQ_EXPORT int zmq_msg_type (zmq_msg *msg);
// Initialise 0SOCKETS context. 'app_threads' specifies maximal number
// of application threads that can have open sockets at the same time.
// 'io_threads' specifies the size of thread pool to handle I/O operations.
//
// Errors: EINVAL - one of the arguments is less than zero or there are no
// threads declared at all.
ZMQ_EXPORT void *zmq_init (int app_threads, int io_threads);
// Deinitialise 0SOCKETS context including all the open sockets. Closing
// sockets after zmq_term has been called will result in undefined behaviour.
ZMQ_EXPORT int zmq_term (void *context);
// Open a socket.
//
// Errors: EINVAL - invalid socket type.
// EMFILE - the number of application threads entitled to hold open
// sockets at the same time was exceeded.
ZMQ_EXPORT void *zmq_socket (void *context, int type);
// Close the socket.
ZMQ_EXPORT int zmq_close (void *s);
// Bind the socket to a particular address.
ZMQ_EXPORT int zmq_bind (void *s, const char *addr, zmq_opts *opts);
// Connect the socket to a particular address.
ZMQ_EXPORT int zmq_connect (void *s, const char *addr, zmq_opts *opts);
// Subscribe for the subset of messages identified by 'criteria' argument.
ZMQ_EXPORT int zmq_subscribe (void *s, const char *criteria);
// Send the message 'msg' to the socket 's'. 'flags' argument can be
// combination of following values:
// ZMQ_NOBLOCK - if message cannot be sent, return immediately.
// ZMQ_NOFLUSH - message won't be sent immediately. It'll be sent with either
// subsequent flushing send or explicit call to zmq_flush
// function.
//
// Errors: EAGAIN - message cannot be sent at the moment (applies only to
// non-blocking send).
// ENOTSUP - function isn't supported by particular socket type.
ZMQ_EXPORT int zmq_send (void *s, zmq_msg *msg, int flags);
// Flush the messages that were send using ZMQ_NOFLUSH flag down the stream.
//
// Errors: ENOTSUP - function isn't supported by particular socket type.
ZMQ_EXPORT int zmq_flush (void *s);
// Send a message from the socket 's'. 'flags' argument can be combination
// of following values:
// ZMQ_NOBLOCK - if message cannot be received, return immediately.
//
// Errors: EAGAIN - message cannot be received at the moment (applies only to
// non-blocking receive).
// ENOTSUP - function isn't supported by particular socket type.
ZMQ_EXPORT int zmq_recv (void *s, zmq_msg *msg, int flags);
#ifdef __cplusplus
}
#endif
#endif
|
