1 /* ========================================================================= 2 zloop - event-driven reactor 3 4 Copyright (c) the Contributors as noted in the AUTHORS file. 5 This file is part of CZMQ, the high-level C binding for 0MQ: 6 http://czmq.zeromq.org. 7 8 This Source Code Form is subject to the terms of the Mozilla Public 9 License, v. 2.0. If a copy of the MPL was not distributed with this 10 file, You can obtain one at http://mozilla.org/MPL/2.0/. 11 ========================================================================= 12 */ 13 14 #ifndef __ZLOOP_H_INCLUDED__ 15 #define __ZLOOP_H_INCLUDED__ 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 // @warning THE FOLLOWING @INTERFACE BLOCK IS AUTO-GENERATED BY ZPROJECT 22 // @warning Please edit the model at "api/zloop.api" to make changes. 23 // @interface 24 // This is a stable class, and may not change except for emergencies. It 25 // is provided in stable builds. 26 // Callback function for reactor socket activity 27 typedef int (zloop_reader_fn) ( 28 zloop_t *loop, zsock_t *reader, void *arg); 29 30 // Callback function for reactor events (low-level) 31 typedef int (zloop_fn) ( 32 zloop_t *loop, zmq_pollitem_t *item, void *arg); 33 34 // Callback for reactor timer events 35 typedef int (zloop_timer_fn) ( 36 zloop_t *loop, int timer_id, void *arg); 37 38 // Create a new zloop reactor 39 CZMQ_EXPORT zloop_t * 40 zloop_new (void); 41 42 // Destroy a reactor 43 CZMQ_EXPORT void 44 zloop_destroy (zloop_t **self_p); 45 46 // Register socket reader with the reactor. When the reader has messages, 47 // the reactor will call the handler, passing the arg. Returns 0 if OK, -1 48 // if there was an error. If you register the same socket more than once, 49 // each instance will invoke its corresponding handler. 50 CZMQ_EXPORT int 51 zloop_reader (zloop_t *self, zsock_t *sock, zloop_reader_fn handler, void *arg); 52 53 // Cancel a socket reader from the reactor. If multiple readers exist for 54 // same socket, cancels ALL of them. 55 CZMQ_EXPORT void 56 zloop_reader_end (zloop_t *self, zsock_t *sock); 57 58 // Configure a registered reader to ignore errors. If you do not set this, 59 // then readers that have errors are removed from the reactor silently. 60 CZMQ_EXPORT void 61 zloop_reader_set_tolerant (zloop_t *self, zsock_t *sock); 62 63 // Register low-level libzmq pollitem with the reactor. When the pollitem 64 // is ready, will call the handler, passing the arg. Returns 0 if OK, -1 65 // if there was an error. If you register the pollitem more than once, each 66 // instance will invoke its corresponding handler. A pollitem with 67 // socket=NULL and fd=0 means 'poll on FD zero'. 68 CZMQ_EXPORT int 69 zloop_poller (zloop_t *self, zmq_pollitem_t *item, zloop_fn handler, void *arg); 70 71 // Cancel a pollitem from the reactor, specified by socket or FD. If both 72 // are specified, uses only socket. If multiple poll items exist for same 73 // socket/FD, cancels ALL of them. 74 CZMQ_EXPORT void 75 zloop_poller_end (zloop_t *self, zmq_pollitem_t *item); 76 77 // Configure a registered poller to ignore errors. If you do not set this, 78 // then poller that have errors are removed from the reactor silently. 79 CZMQ_EXPORT void 80 zloop_poller_set_tolerant (zloop_t *self, zmq_pollitem_t *item); 81 82 // Register a timer that expires after some delay and repeats some number of 83 // times. At each expiry, will call the handler, passing the arg. To run a 84 // timer forever, use 0 times. Returns a timer_id that is used to cancel the 85 // timer in the future. Returns -1 if there was an error. 86 CZMQ_EXPORT int 87 zloop_timer (zloop_t *self, size_t delay, size_t times, zloop_timer_fn handler, void *arg); 88 89 // Cancel a specific timer identified by a specific timer_id (as returned by 90 // zloop_timer). 91 CZMQ_EXPORT int 92 zloop_timer_end (zloop_t *self, int timer_id); 93 94 // Register a ticket timer. Ticket timers are very fast in the case where 95 // you use a lot of timers (thousands), and frequently remove and add them. 96 // The main use case is expiry timers for servers that handle many clients, 97 // and which reset the expiry timer for each message received from a client. 98 // Whereas normal timers perform poorly as the number of clients grows, the 99 // cost of ticket timers is constant, no matter the number of clients. You 100 // must set the ticket delay using zloop_set_ticket_delay before creating a 101 // ticket. Returns a handle to the timer that you should use in 102 // zloop_ticket_reset and zloop_ticket_delete. 103 CZMQ_EXPORT void * 104 zloop_ticket (zloop_t *self, zloop_timer_fn handler, void *arg); 105 106 // Reset a ticket timer, which moves it to the end of the ticket list and 107 // resets its execution time. This is a very fast operation. 108 CZMQ_EXPORT void 109 zloop_ticket_reset (zloop_t *self, void *handle); 110 111 // Delete a ticket timer. We do not actually delete the ticket here, as 112 // other code may still refer to the ticket. We mark as deleted, and remove 113 // later and safely. 114 CZMQ_EXPORT void 115 zloop_ticket_delete (zloop_t *self, void *handle); 116 117 // Set the ticket delay, which applies to all tickets. If you lower the 118 // delay and there are already tickets created, the results are undefined. 119 CZMQ_EXPORT void 120 zloop_set_ticket_delay (zloop_t *self, size_t ticket_delay); 121 122 // Set hard limit on number of timers allowed. Setting more than a small 123 // number of timers (10-100) can have a dramatic impact on the performance 124 // of the reactor. For high-volume cases, use ticket timers. If the hard 125 // limit is reached, the reactor stops creating new timers and logs an 126 // error. 127 CZMQ_EXPORT void 128 zloop_set_max_timers (zloop_t *self, size_t max_timers); 129 130 // Set verbose tracing of reactor on/off. The default verbose setting is 131 // off (false). 132 CZMQ_EXPORT void 133 zloop_set_verbose (zloop_t *self, bool verbose); 134 135 // By default the reactor stops if the process receives a SIGINT or SIGTERM 136 // signal. This makes it impossible to shut-down message based architectures 137 // like zactors. This method lets you switch off break handling. The default 138 // nonstop setting is off (false). 139 CZMQ_EXPORT void 140 zloop_set_nonstop (zloop_t *self, bool nonstop); 141 142 // Start the reactor. Takes control of the thread and returns when the 0MQ 143 // context is terminated or the process is interrupted, or any event handler 144 // returns -1. Event handlers may register new sockets and timers, and 145 // cancel sockets. Returns 0 if interrupted, -1 if canceled by a handler. 146 CZMQ_EXPORT int 147 zloop_start (zloop_t *self); 148 149 // Self test of this class. 150 CZMQ_EXPORT void 151 zloop_test (bool verbose); 152 153 // @end 154 155 156 // Deprecated method aliases 157 #define zloop_set_tolerant(s,i) zloop_poller_set_tolerant(s,i) 158 159 #ifdef __cplusplus 160 } 161 #endif 162 163 #endif 164