[mirror_frr.git] / lib / frr_zmq.h

/*
 * libzebra ZeroMQ bindings
 * Copyright (C) 2015  David Lamparter
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 2 of the License, or (at your option)
 * any later version.
 *
 * This program 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 GNU General Public License for
 * more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; see the file COPYING; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef _FRRZMQ_H
#define _FRRZMQ_H

#include "thread.h"
#include <zmq.h>

/* linking/packaging note:  this is a separate library that needs to be
 * linked into any daemon/library/module that wishes to use its
 * functionality.  The purpose of this is to encapsulate the libzmq
 * dependency and not make libfrr/FRR itself depend on libzmq.
 *
 * libfrrzmq should be put in LDFLAGS/LIBADD *before* either libfrr or
 * libzmq, and both of these should always be listed, e.g.
 *   foo_LDFLAGS = libfrrzmq.la libfrr.la $(ZEROMQ_LIBS)
 */

/* libzmq's context
 *
 * this is mostly here as a convenience, it has IPv6 enabled but nothing
 * else is tied to it;  you can use a separate context without problems
 */
extern void *frrzmq_context;

extern void frrzmq_init (void);
extern void frrzmq_finish (void);

#define debugargdef const char *funcname, const char *schedfrom, int fromln

/* core event registration, one of these 2 macros should be used */
#define frrzmq_thread_add_read_msg(m,f,a,z) funcname_frrzmq_thread_add_read( \
				m,f,NULL,a,z,#f,__FILE__,__LINE__)
#define frrzmq_thread_add_read_part(m,f,a,z) funcname_frrzmq_thread_add_read( \
				m,NULL,f,a,z,#f,__FILE__,__LINE__)

struct frrzmq_cb;

/* Set up a POLLIN notification to be called from the libfrr main loop.
 * This has the following properties:
 *
 * - since ZeroMQ works with edge triggered notifications, it will loop and
 *   dispatch as many events as ZeroMQ has pending at the time libfrr calls
 *   into this code
 * - due to this looping (which means it non-single-issue), the callback is
 *   also persistent.  Do _NOT_ re-register the event inside of your
 *   callback function.
 * - either msgfunc or partfunc will be called (only one can be specified)
 *   - msgfunc is called once for each incoming message
 *   - if partfunc is specified, the message is read and partfunc is called
 *     for each ZeroMQ multi-part subpart.  Note that you can't send replies
 *     before all parts have been read because that violates the ZeroMQ FSM.
 * - you can safely cancel the callback from within itself
 * - installing a callback will check for pending events (ZMQ_EVENTS) and
 *   may schedule the event to run as soon as libfrr is back in its main
 *   loop.
 *
 * TODO #1: add ZMQ_POLLERR / error callback
 * TODO #2: add frrzmq_check_events() function to check for edge triggered
 *          things that may have happened after a zmq_send() call or so
 */
extern struct frrzmq_cb *funcname_frrzmq_thread_add_read(
		struct thread_master *master,
		void (*msgfunc)(void *arg, void *zmqsock),
		void (*partfunc)(void *arg, void *zmqsock,
				 zmq_msg_t *msg, unsigned partnum),
		void *arg, void *zmqsock, debugargdef);

extern void frrzmq_thread_cancel(struct frrzmq_cb *cb);

#endif /* _FRRZMQ_H */
Commit	Line	Data
b6116506 DL	1	/*
	2	* libzebra ZeroMQ bindings
	3	* Copyright (C) 2015 David Lamparter
	4	*
	5	* This program is free software; you can redistribute it and/or modify it
	6	* under the terms of the GNU General Public License as published by the Free
	7	* Software Foundation; either version 2 of the License, or (at your option)
	8	* any later version.
	9	*
	10	* This program is distributed in the hope that it will be useful, but WITHOUT
	11	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	12	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
	13	* more details.
	14	*
	15	* You should have received a copy of the GNU General Public License along
	16	* with this program; see the file COPYING; if not, write to the Free Software
	17	* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
	18	*/
	19
	20	#ifndef _FRRZMQ_H
	21	#define _FRRZMQ_H
	22
	23	#include "thread.h"
	24	#include <zmq.h>
	25
f3cd305f DL	26	/* linking/packaging note: this is a separate library that needs to be
	27	* linked into any daemon/library/module that wishes to use its
	28	* functionality. The purpose of this is to encapsulate the libzmq
	29	* dependency and not make libfrr/FRR itself depend on libzmq.
	30	*
	31	* libfrrzmq should be put in LDFLAGS/LIBADD before either libfrr or
	32	* libzmq, and both of these should always be listed, e.g.
	33	* foo_LDFLAGS = libfrrzmq.la libfrr.la $(ZEROMQ_LIBS)
	34	*/
	35
	36	/* libzmq's context
	37	*
	38	* this is mostly here as a convenience, it has IPv6 enabled but nothing
	39	* else is tied to it; you can use a separate context without problems
	40	*/
b6116506 DL	41	extern void *frrzmq_context;
	42
	43	extern void frrzmq_init (void);
	44	extern void frrzmq_finish (void);
	45
	46	#define debugargdef const char funcname, const char schedfrom, int fromln
	47
f3cd305f	48	/* core event registration, one of these 2 macros should be used */
b6116506 DL	49	#define frrzmq_thread_add_read_msg(m,f,a,z) funcname_frrzmq_thread_add_read( \
	50	m,f,NULL,a,z,#f,__FILE__,__LINE__)
	51	#define frrzmq_thread_add_read_part(m,f,a,z) funcname_frrzmq_thread_add_read( \
	52	m,NULL,f,a,z,#f,__FILE__,__LINE__)
	53
	54	struct frrzmq_cb;
	55
f3cd305f DL	56	/* Set up a POLLIN notification to be called from the libfrr main loop.
	57	* This has the following properties:
	58	*
	59	* - since ZeroMQ works with edge triggered notifications, it will loop and
	60	* dispatch as many events as ZeroMQ has pending at the time libfrr calls
	61	* into this code
	62	* - due to this looping (which means it non-single-issue), the callback is
	63	* also persistent. Do _NOT_ re-register the event inside of your
	64	* callback function.
	65	* - either msgfunc or partfunc will be called (only one can be specified)
	66	* - msgfunc is called once for each incoming message
	67	* - if partfunc is specified, the message is read and partfunc is called
	68	* for each ZeroMQ multi-part subpart. Note that you can't send replies
	69	* before all parts have been read because that violates the ZeroMQ FSM.
	70	* - you can safely cancel the callback from within itself
	71	* - installing a callback will check for pending events (ZMQ_EVENTS) and
	72	* may schedule the event to run as soon as libfrr is back in its main
	73	* loop.
	74	*
	75	* TODO #1: add ZMQ_POLLERR / error callback
	76	* TODO #2: add frrzmq_check_events() function to check for edge triggered
	77	* things that may have happened after a zmq_send() call or so
	78	*/
b6116506 DL	79	extern struct frrzmq_cb *funcname_frrzmq_thread_add_read(
	80	struct thread_master *master,
	81	void (msgfunc)(void arg, void *zmqsock),
	82	void (partfunc)(void arg, void *zmqsock,
	83	zmq_msg_t *msg, unsigned partnum),
	84	void arg, void zmqsock, debugargdef);
	85
	86	extern void frrzmq_thread_cancel(struct frrzmq_cb *cb);
	87
	88	#endif /* _FRRZMQ_H */