2009-07-29 12:07:54 +02:00
|
|
|
/*
|
|
|
|
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/>.
|
|
|
|
*/
|
|
|
|
|
2009-08-03 11:30:13 +02:00
|
|
|
#ifndef __ZMQ_H_INCLUDED__
|
|
|
|
#define __ZMQ_H_INCLUDED__
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
|
|
extern "C" {
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#include <stddef.h>
|
|
|
|
#include <stdint.h>
|
|
|
|
|
2009-08-03 11:30:13 +02:00
|
|
|
#if defined MSC_VER && defined ZMQ_BUILDING_LIBZMQ
|
|
|
|
#define ZMQ_EXPORT __declspec(dllexport)
|
2009-07-29 12:07:54 +02:00
|
|
|
#else
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_EXPORT
|
2009-07-29 12:07:54 +02:00
|
|
|
#endif
|
|
|
|
|
|
|
|
// Maximal size of "Very Small Message". VSMs are passed by value
|
|
|
|
// to avoid excessive memory allocation/deallocation.
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_MAX_VSM_SIZE 30
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Message & notification types.
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_GAP 1
|
|
|
|
#define ZMQ_DELIMITER 31
|
|
|
|
#define ZMQ_VSM 32
|
2009-07-29 12:07:54 +02:00
|
|
|
|
2009-08-09 09:24:48 +02:00
|
|
|
// Socket options.
|
|
|
|
#define ZMQ_HWM 1
|
|
|
|
#define ZMQ_LWM 2
|
|
|
|
#define ZMQ_SWAP 3
|
|
|
|
#define ZMQ_MASK 4
|
|
|
|
#define ZMQ_AFFINITY 5
|
|
|
|
#define ZMQ_SESSIONID 6
|
|
|
|
|
2009-07-29 12:07:54 +02:00
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_NOBLOCK 1
|
2009-07-29 12:07:54 +02:00
|
|
|
|
2009-08-03 11:30:13 +02:00
|
|
|
// zmq_send should not flush the message downstream immediately. Instead, it
|
|
|
|
// should batch ZMQ_NOFLUSH messages and send them downstream only if zmq_flush
|
2009-07-29 12:07:54 +02:00
|
|
|
// 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
|
2009-08-03 11:30:13 +02:00
|
|
|
// example for illustration of ZMQ_NOFLUSH functionality.
|
|
|
|
#define ZMQ_NOFLUSH 2
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_P2P 0
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Socket to distribute data. Recv fuction is not implemeted for this socket
|
|
|
|
// type. Messages are distributed in fanout fashion to all peers.
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_PUB 1
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_SUB 2
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_REQ 3
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
#define ZMQ_REP 4
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Prototype for the message body deallocation functions.
|
|
|
|
// It is deliberately defined in the way to comply with standard C free.
|
2009-08-03 11:30:13 +02:00
|
|
|
typedef void (zmq_free_fn) (void *data);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// A message. If 'shared' is true, message content pointed to by 'content'
|
|
|
|
// is shared, i.e. reference counting is used to manage its lifetime
|
2009-08-03 11:30:13 +02:00
|
|
|
// rather than straighforward malloc/free. struct zmq_msg_content is
|
2009-07-29 12:07:54 +02:00
|
|
|
// not declared in the API.
|
2009-08-03 11:30:13 +02:00
|
|
|
struct zmq_msg
|
2009-07-29 12:07:54 +02:00
|
|
|
{
|
2009-08-03 11:30:13 +02:00
|
|
|
struct zmq_msg_content *content;
|
2009-07-29 12:07:54 +02:00
|
|
|
unsigned char shared;
|
|
|
|
uint16_t vsm_size;
|
2009-08-03 11:30:13 +02:00
|
|
|
unsigned char vsm_data [ZMQ_MAX_VSM_SIZE];
|
2009-07-29 12:07:54 +02:00
|
|
|
};
|
|
|
|
|
|
|
|
// Initialise an empty message (zero bytes long).
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_msg_init (zmq_msg *msg);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Initialise a message 'size' bytes long.
|
|
|
|
//
|
|
|
|
// Errors: ENOMEM - the size is too large to allocate.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_msg_init_size (zmq_msg *msg, size_t size);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_msg_init_data (zmq_msg *msg, void *data, size_t size,
|
|
|
|
zmq_free_fn *ffn);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Deallocate the message.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_msg_close (zmq_msg *msg);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_msg_move (zmq_msg *dest, zmq_msg *src);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_msg_copy (zmq_msg *dest, zmq_msg *src);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Returns pointer to message data.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT void *zmq_msg_data (zmq_msg *msg);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Return size of message data (in bytes).
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT size_t zmq_msg_size (zmq_msg *msg);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Returns type of the message.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_msg_type (zmq_msg *msg);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT void *zmq_init (int app_threads, int io_threads);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Deinitialise 0SOCKETS context including all the open sockets. Closing
|
2009-08-03 11:30:13 +02:00
|
|
|
// sockets after zmq_term has been called will result in undefined behaviour.
|
|
|
|
ZMQ_EXPORT int zmq_term (void *context);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// 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.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT void *zmq_socket (void *context, int type);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Close the socket.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_close (void *s);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
2009-08-09 09:24:48 +02:00
|
|
|
// Sets an option on the socket.
|
2009-08-09 11:57:21 +02:00
|
|
|
// EINVAL - unknown option, a value with incorrect length or an invalid value.
|
2009-08-09 09:24:48 +02:00
|
|
|
ZMQ_EXPORT int zmq_setsockopt (void *s, int option_, void *optval_,
|
|
|
|
size_t optvallen_);
|
|
|
|
|
2009-07-29 12:07:54 +02:00
|
|
|
// Bind the socket to a particular address.
|
2009-08-09 09:24:48 +02:00
|
|
|
ZMQ_EXPORT int zmq_bind (void *s, const char *addr);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Connect the socket to a particular address.
|
2009-08-09 09:24:48 +02:00
|
|
|
ZMQ_EXPORT int zmq_connect (void *s, const char *addr);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Subscribe for the subset of messages identified by 'criteria' argument.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_subscribe (void *s, const char *criteria);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Send the message 'msg' to the socket 's'. 'flags' argument can be
|
|
|
|
// combination of following values:
|
2009-08-03 11:30:13 +02:00
|
|
|
// 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.
|
2009-07-29 12:07:54 +02:00
|
|
|
//
|
|
|
|
// Errors: EAGAIN - message cannot be sent at the moment (applies only to
|
|
|
|
// non-blocking send).
|
|
|
|
// ENOTSUP - function isn't supported by particular socket type.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_send (void *s, zmq_msg *msg, int flags);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
2009-08-03 11:30:13 +02:00
|
|
|
// Flush the messages that were send using ZMQ_NOFLUSH flag down the stream.
|
2009-07-29 12:07:54 +02:00
|
|
|
//
|
|
|
|
// Errors: ENOTSUP - function isn't supported by particular socket type.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_flush (void *s);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
// Send a message from the socket 's'. 'flags' argument can be combination
|
|
|
|
// of following values:
|
2009-08-03 11:30:13 +02:00
|
|
|
// ZMQ_NOBLOCK - if message cannot be received, return immediately.
|
2009-07-29 12:07:54 +02:00
|
|
|
//
|
|
|
|
// Errors: EAGAIN - message cannot be received at the moment (applies only to
|
|
|
|
// non-blocking receive).
|
|
|
|
// ENOTSUP - function isn't supported by particular socket type.
|
2009-08-03 11:30:13 +02:00
|
|
|
ZMQ_EXPORT int zmq_recv (void *s, zmq_msg *msg, int flags);
|
2009-07-29 12:07:54 +02:00
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
|
|
}
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#endif
|