libevent: event2/rpc.h Source File

libevent 2.1.12 Event notification library

rpc.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2006-2007 Niels Provos <provos@citi.umich.edu>
3 * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
13 * 3. The name of the author may not be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27#ifndef EVENT2_RPC_H_INCLUDED_
28#define EVENT2_RPC_H_INCLUDED_
29
30/* For int types. */
31#include <event2/util.h>
32#include <event2/visibility.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
80#define EVTAG_HAS(msg, member) \
81 ((msg)->member##_set == 1)
82
83#ifndef EVENT2_RPC_COMPAT_H_INCLUDED_
84
92#define EVTAG_ASSIGN(msg, member, value) \
93 (*(msg)->base->member##_assign)((msg), (value))
102#define EVTAG_ASSIGN_WITH_LEN(msg, member, value, len) \
103 (*(msg)->base->member##_assign)((msg), (value), (len))
112#define EVTAG_GET(msg, member, pvalue) \
113 (*(msg)->base->member##_get)((msg), (pvalue))
123#define EVTAG_GET_WITH_LEN(msg, member, pvalue, plen) \
124 (*(msg)->base->member##_get)((msg), (pvalue), (plen))
125
126#endif /* EVENT2_RPC_COMPAT_H_INCLUDED_ */
127
131#define EVTAG_ARRAY_ADD_VALUE(msg, member, value) \
132 (*(msg)->base->member##_add)((msg), (value))
136#define EVTAG_ARRAY_ADD(msg, member) \
137 (*(msg)->base->member##_add)(msg)
141#define EVTAG_ARRAY_GET(msg, member, offset, pvalue) \
142 (*(msg)->base->member##_get)((msg), (offset), (pvalue))
146#define EVTAG_ARRAY_LEN(msg, member) ((msg)->member##_length)
147
148
149struct evbuffer;
150struct event_base;
151struct evrpc_req_generic;
152struct evrpc_request_wrapper;
153struct evrpc;
154
159#define EVRPC_STRUCT(rpcname) struct evrpc_req__##rpcname
160
161struct evhttp_request;
162struct evrpc_status;
163struct evrpc_hook_meta;
164
176#define EVRPC_HEADER(rpcname, reqstruct, rplystruct) \
177EVRPC_STRUCT(rpcname) { \
178 struct evrpc_hook_meta *hook_meta; \
179 struct reqstruct* request; \
180 struct rplystruct* reply; \
181 struct evrpc* rpc; \
182 struct evhttp_request* http_req; \
183 struct evbuffer* rpc_data; \
184}; \
185EVENT2_EXPORT_SYMBOL \
186int evrpc_send_request_##rpcname(struct evrpc_pool *, \
187 struct reqstruct *, struct rplystruct *, \
188 void (*)(struct evrpc_status *, \
189 struct reqstruct *, struct rplystruct *, void *cbarg), \
190 void *);
191
192struct evrpc_pool;
193
195EVENT2_EXPORT_SYMBOL
196 struct evrpc_request_wrapper *evrpc_make_request_ctx(
197 struct evrpc_pool *pool, void *request, void *reply,
198 const char *rpcname,
199 void (*req_marshal)(struct evbuffer*, void *),
200 void (*rpl_clear)(void *),
201 int (*rpl_unmarshal)(void *, struct evbuffer *),
202 void (*cb)(struct evrpc_status *, void *, void *, void *),
203 void *cbarg);
204
219#define EVRPC_MAKE_CTX(rpcname, reqstruct, rplystruct, \
220 pool, request, reply, cb, cbarg) \
221 evrpc_make_request_ctx(pool, request, reply, \
222 #rpcname, \
223 (void (*)(struct evbuffer *, void *))reqstruct##_marshal, \
224 (void (*)(void *))rplystruct##_clear, \
225 (int (*)(void *, struct evbuffer *))rplystruct##_unmarshal, \
226 (void (*)(struct evrpc_status *, void *, void *, void *))cb, \
227 cbarg)
228
239#define EVRPC_GENERATE(rpcname, reqstruct, rplystruct) \
240 int evrpc_send_request_##rpcname(struct evrpc_pool *pool, \
241 struct reqstruct *request, struct rplystruct *reply, \
242 void (*cb)(struct evrpc_status *, \
243 struct reqstruct *, struct rplystruct *, void *cbarg), \
244 void *cbarg) { \
245 return evrpc_send_request_generic(pool, request, reply, \
246 (void (*)(struct evrpc_status *, void *, void *, void *))cb, \
247 cbarg, \
248 #rpcname, \
249 (void (*)(struct evbuffer *, void *))reqstruct##_marshal, \
250 (void (*)(void *))rplystruct##_clear, \
251 (int (*)(void *, struct evbuffer *))rplystruct##_unmarshal); \
252}
253
263#define EVRPC_REQUEST_HTTP(rpc_req) (rpc_req)->http_req
264
266EVENT2_EXPORT_SYMBOL
267 void evrpc_request_done(struct evrpc_req_generic *req);
268
270EVENT2_EXPORT_SYMBOL
271 void *evrpc_get_request(struct evrpc_req_generic *req);
272EVENT2_EXPORT_SYMBOL
273void *evrpc_get_reply(struct evrpc_req_generic *req);
274
283#define EVRPC_REQUEST_DONE(rpc_req) do { \
284 struct evrpc_req_generic *req_ = (struct evrpc_req_generic *)(rpc_req); \
285 evrpc_request_done(req_); \
286} while (0)
287
288
289struct evrpc_base;
290struct evhttp;
291
292/* functions to start up the rpc system */
293
300EVENT2_EXPORT_SYMBOL
301 struct evrpc_base *evrpc_init(struct evhttp *server);
302
311EVENT2_EXPORT_SYMBOL
312 void evrpc_free(struct evrpc_base *base);
313
330#define EVRPC_REGISTER(base, name, request, reply, callback, cbarg) \
331 evrpc_register_generic(base, #name, \
332 (void (*)(struct evrpc_req_generic *, void *))callback, cbarg, \
333 (void *(*)(void *))request##_new_with_arg, NULL, \
334 (void (*)(void *))request##_free, \
335 (int (*)(void *, struct evbuffer *))request##_unmarshal, \
336 (void *(*)(void *))reply##_new_with_arg, NULL, \
337 (void (*)(void *))reply##_free, \
338 (int (*)(void *))reply##_complete, \
339 (void (*)(struct evbuffer *, void *))reply##_marshal)
340
348EVENT2_EXPORT_SYMBOL
349 int evrpc_register_rpc(struct evrpc_base *, struct evrpc *,
350 void (*)(struct evrpc_req_generic*, void *), void *);
351
360#define EVRPC_UNREGISTER(base, name) evrpc_unregister_rpc((base), #name)
361
362EVENT2_EXPORT_SYMBOL
363int evrpc_unregister_rpc(struct evrpc_base *base, const char *name);
364
365/*
366 * Client-side RPC support
367 */
368
369struct evhttp_connection;
370struct evrpc_status;
371
387#define EVRPC_MAKE_REQUEST(name, pool, request, reply, cb, cbarg) \
388 evrpc_send_request_##name((pool), (request), (reply), (cb), (cbarg))
389
401EVENT2_EXPORT_SYMBOL
402 int evrpc_make_request(struct evrpc_request_wrapper *ctx);
403
415EVENT2_EXPORT_SYMBOL
416 struct evrpc_pool *evrpc_pool_new(struct event_base *base);
422EVENT2_EXPORT_SYMBOL
423 void evrpc_pool_free(struct evrpc_pool *pool);
424
433EVENT2_EXPORT_SYMBOL
434 void evrpc_pool_add_connection(struct evrpc_pool *pool,
435 struct evhttp_connection *evcon);
436
445EVENT2_EXPORT_SYMBOL
446 void evrpc_pool_remove_connection(struct evrpc_pool *pool,
447 struct evhttp_connection *evcon);
448
464EVENT2_EXPORT_SYMBOL
465 void evrpc_pool_set_timeout(struct evrpc_pool *pool, int timeout_in_secs);
466
472 enum EVRPC_HOOK_TYPE {
473 EVRPC_INPUT,
474 EVRPC_OUTPUT
475};
476
477#ifndef _WIN32
480#define INPUT EVRPC_INPUT
483#define OUTPUT EVRPC_OUTPUT
484#endif
485
490 enum EVRPC_HOOK_RESULT {
491 EVRPC_TERMINATE = -1,
492 EVRPC_CONTINUE = 0,
493 EVRPC_PAUSE = 1
494};
495
512EVENT2_EXPORT_SYMBOL
513 void *evrpc_add_hook(void *vbase,
514 enum EVRPC_HOOK_TYPE hook_type,
515 int (*cb)(void *, struct evhttp_request *, struct evbuffer *, void *),
516 void *cb_arg);
517
526EVENT2_EXPORT_SYMBOL
527 int evrpc_remove_hook(void *vbase,
528 enum EVRPC_HOOK_TYPE hook_type,
529 void *handle);
530
536EVENT2_EXPORT_SYMBOL
537 int evrpc_resume_request(void *vbase, void *ctx, enum EVRPC_HOOK_RESULT res);
538
550EVENT2_EXPORT_SYMBOL
551 void evrpc_hook_add_meta(void *ctx, const char *key,
552 const void *data, size_t data_size);
553
564EVENT2_EXPORT_SYMBOL
565 int evrpc_hook_find_meta(void *ctx, const char *key,
566 void **data, size_t *data_size);
567
575EVENT2_EXPORT_SYMBOL
576 struct evhttp_connection *evrpc_hook_get_connection(void *ctx);
577
585EVENT2_EXPORT_SYMBOL
586 int evrpc_send_request_generic(struct evrpc_pool *pool,
587 void *request, void *reply,
588 void (*cb)(struct evrpc_status *, void *, void *, void *),
589 void *cb_arg,
590 const char *rpcname,
591 void (*req_marshal)(struct evbuffer *, void *),
592 void (*rpl_clear)(void *),
593 int (*rpl_unmarshal)(void *, struct evbuffer *));
594
602EVENT2_EXPORT_SYMBOL
603 int evrpc_register_generic(struct evrpc_base *base, const char *name,
604 void (*callback)(struct evrpc_req_generic *, void *), void *cbarg,
605 void *(*req_new)(void *), void *req_new_arg, void (*req_free)(void *),
606 int (*req_unmarshal)(void *, struct evbuffer *),
607 void *(*rpl_new)(void *), void *rpl_new_arg, void (*rpl_free)(void *),
608 int (*rpl_complete)(void *),
609 void (*rpl_marshal)(struct evbuffer *, void *));
610
612EVENT2_EXPORT_SYMBOL
613 struct evrpc_pool* evrpc_request_get_pool(struct evrpc_request_wrapper *ctx);
614EVENT2_EXPORT_SYMBOL
615void evrpc_request_set_pool(struct evrpc_request_wrapper *ctx,
616 struct evrpc_pool *pool);
617EVENT2_EXPORT_SYMBOL
618void evrpc_request_set_cb(struct evrpc_request_wrapper *ctx,
619 void (*cb)(struct evrpc_status*, void *request, void *reply, void *arg),
620 void *cb_arg);
621
622#ifdef __cplusplus
623}
624#endif
625
626#endif /* EVENT2_RPC_H_INCLUDED_ */
evrpc_pool_set_timeout
EVENT2_EXPORT_SYMBOL void evrpc_pool_set_timeout(struct evrpc_pool *pool, int timeout_in_secs)
Sets the timeout in secs after which a request has to complete.
evrpc_hook_get_connection
EVENT2_EXPORT_SYMBOL struct evhttp_connection * evrpc_hook_get_connection(void *ctx)
returns the connection object associated with the request
evrpc_make_request_ctx
EVENT2_EXPORT_SYMBOL struct evrpc_request_wrapper * evrpc_make_request_ctx(struct evrpc_pool *pool, void *request, void *reply, const char *rpcname, void(*req_marshal)(struct evbuffer *, void *), void(*rpl_clear)(void *), int(*rpl_unmarshal)(void *, struct evbuffer *), void(*cb)(struct evrpc_status *, void *, void *, void *), void *cbarg)
use EVRPC_GENERATE instead
evrpc_make_request
EVENT2_EXPORT_SYMBOL int evrpc_make_request(struct evrpc_request_wrapper *ctx)
Makes an RPC request based on the provided context.
evrpc_pool_new
EVENT2_EXPORT_SYMBOL struct evrpc_pool * evrpc_pool_new(struct event_base *base)
creates an rpc connection pool
evrpc_hook_find_meta
EVENT2_EXPORT_SYMBOL int evrpc_hook_find_meta(void *ctx, const char *key, void **data, size_t *data_size)
retrieves meta data previously associated
evrpc_pool_remove_connection
EVENT2_EXPORT_SYMBOL void evrpc_pool_remove_connection(struct evrpc_pool *pool, struct evhttp_connection *evcon)
Removes a connection from the pool.
EVRPC_HOOK_TYPE
EVRPC_HOOK_TYPE
Hooks for changing the input and output of RPCs; this can be used to implement compression,...
Definition: rpc.h:472
EVRPC_INPUT
@ EVRPC_INPUT
apply the function to an input hook
Definition: rpc.h:473
EVRPC_OUTPUT
@ EVRPC_OUTPUT
apply the function to an output hook
Definition: rpc.h:474
evrpc_request_done
EVENT2_EXPORT_SYMBOL void evrpc_request_done(struct evrpc_req_generic *req)
completes the server response to an rpc request
evrpc_get_request
EVENT2_EXPORT_SYMBOL void * evrpc_get_request(struct evrpc_req_generic *req)
accessors for request and reply
evrpc_resume_request
EVENT2_EXPORT_SYMBOL int evrpc_resume_request(void *vbase, void *ctx, enum EVRPC_HOOK_RESULT res)
resume a paused request
evrpc_add_hook
EVENT2_EXPORT_SYMBOL void * evrpc_add_hook(void *vbase, enum EVRPC_HOOK_TYPE hook_type, int(*cb)(void *, struct evhttp_request *, struct evbuffer *, void *), void *cb_arg)
adds a processing hook to either an rpc base or rpc pool
evrpc_hook_add_meta
EVENT2_EXPORT_SYMBOL void evrpc_hook_add_meta(void *ctx, const char *key, const void *data, size_t data_size)
adds meta data to request
evrpc_send_request_generic
EVENT2_EXPORT_SYMBOL int evrpc_send_request_generic(struct evrpc_pool *pool, void *request, void *reply, void(*cb)(struct evrpc_status *, void *, void *, void *), void *cb_arg, const char *rpcname, void(*req_marshal)(struct evbuffer *, void *), void(*rpl_clear)(void *), int(*rpl_unmarshal)(void *, struct evbuffer *))
Function for sending a generic RPC request.
EVRPC_HOOK_RESULT
EVRPC_HOOK_RESULT
Return value from hook processing functions.
Definition: rpc.h:490
EVRPC_CONTINUE
@ EVRPC_CONTINUE
continue processing the rpc
Definition: rpc.h:492
EVRPC_TERMINATE
@ EVRPC_TERMINATE
indicates the rpc should be terminated
Definition: rpc.h:491
EVRPC_PAUSE
@ EVRPC_PAUSE
pause processing request until resumed
Definition: rpc.h:493
evrpc_pool_add_connection
EVENT2_EXPORT_SYMBOL void evrpc_pool_add_connection(struct evrpc_pool *pool, struct evhttp_connection *evcon)
Adds a connection over which rpc can be dispatched to the pool.
evrpc_request_get_pool
EVENT2_EXPORT_SYMBOL struct evrpc_pool * evrpc_request_get_pool(struct evrpc_request_wrapper *ctx)
accessors for obscure and undocumented functionality
evrpc_register_generic
EVENT2_EXPORT_SYMBOL int evrpc_register_generic(struct evrpc_base *base, const char *name, void(*callback)(struct evrpc_req_generic *, void *), void *cbarg, void *(*req_new)(void *), void *req_new_arg, void(*req_free)(void *), int(*req_unmarshal)(void *, struct evbuffer *), void *(*rpl_new)(void *), void *rpl_new_arg, void(*rpl_free)(void *), int(*rpl_complete)(void *), void(*rpl_marshal)(struct evbuffer *, void *))
Function for registering a generic RPC with the RPC base.
evrpc_remove_hook
EVENT2_EXPORT_SYMBOL int evrpc_remove_hook(void *vbase, enum EVRPC_HOOK_TYPE hook_type, void *handle)
removes a previously added hook
evrpc_pool_free
EVENT2_EXPORT_SYMBOL void evrpc_pool_free(struct evrpc_pool *pool)
frees an rpc connection pool
evrpc_register_rpc
EVENT2_EXPORT_SYMBOL int evrpc_register_rpc(struct evrpc_base *, struct evrpc *, void(*)(struct evrpc_req_generic *, void *), void *)
Low level function for registering an RPC with a server.
evrpc_free
EVENT2_EXPORT_SYMBOL void evrpc_free(struct evrpc_base *base)
Frees the evrpc base.
evrpc_init
EVENT2_EXPORT_SYMBOL struct evrpc_base * evrpc_init(struct evhttp *server)
Creates a new rpc base from which RPC requests can be received.
evbuffer
An evbuffer is an opaque data type for efficiently buffering data to be sent or received on the netwo...
Definition: buffer.h:99
event_base
Structure to hold information and state for a Libevent dispatch loop.
Definition: event.h:219
util.h
Common convenience functions for cross-platform portability and related socket manipulations.