PageRenderTime 67ms CodeModel.GetById 29ms RepoModel.GetById 0ms app.codeStats 0ms

/doc/api/events.txt

https://bitbucket.org/dpaulus/ircu-patchq-base
Plain Text | 816 lines | 653 code | 163 blank | 0 comment | 0 complexity | 8c284f8d4eddf26daf78660d2fa1bf5e MD5 | raw file
Possible License(s): AGPL-1.0
  1. The IRC server is built around an event loop. Until the u2.10.11
  2. release, this event loop has been rather ad-hoc; timed events are
  3. hard-coded in, signals are handled inside the signal handler, etc.
  4. All of this has changed with u2.10.11. A new subsystem, the events
  5. subsystem, has been introduced; the new subsystem contains a
  6. generalization of the concept of an event. An event is a signal, the
  7. expiration of a timer, or some form of activity on a network socket.
  8. This new subsystem has the potential to vastly simplify the code that
  9. is arguably the core of any network program, and makes it much simpler
  10. to support more exotic forms of network activity monitoring than the
  11. conventional select() and poll() calls.
  12. The primary concepts that the events subsystem works with are the
  13. "event," represented by a struct Event, and the "generator." There
  14. are three types of generators: sockets, represented by struct Socket;
  15. signals, represented by struct Signal; and timers, represented by
  16. struct Timer. Each of these generators will be described in turn.
  17. Signals
  18. The signal is perhaps the simplest generator in the entire events
  19. subsystem. Basically, instead of setting a signal handler, the
  20. function signal_add() is called, specifying a function to be called
  21. when a given signal is detected. Most importantly, that call-back
  22. function is called _outside_ the context of a signal handler,
  23. permitting the call-back to use more exotic functions that are
  24. anathema within a signal handler, such as MyMalloc(). Once a
  25. call-back for a signal has been established, it cannot be deleted;
  26. this design decision was driven by the fact that ircd never changes
  27. its signal handlers.
  28. Whenever a signal is received, an event of type ET_SIGNAL is
  29. generated, and that event is passed to the event call-back function
  30. specified in the signal_add() call.
  31. Timers
  32. Execution of the call-back functions for a timer occur when that timer
  33. _expires_; when a timer expires depends on the type of timer and the
  34. expiration time that was used for that timer. A TT_ABSOLUTE timer,
  35. for instance, expires at exactly the time given as the expiration
  36. time. This time is a standard UNIX time_t value, measuring seconds
  37. since the UNIX epoch. The TT_ABSOLUTE timer type is complemented by
  38. the TT_RELATIVE timer; the time passed as its expiration time is
  39. relative to the current time. If a TT_RELATIVE timer is given an
  40. expiration time of 5, for instance, it will expire 5 seconds after the
  41. present time. Internally, TT_RELATIVE timers are converted into
  42. TT_ABSOLUTE timers, with the expiration time adjusted by addition of
  43. the current time.
  44. Those two types of timers, TT_ABSOLUTE and TT_RELATIVE, are
  45. single-shot timers. Once they expire, they are removed from the timer
  46. list unless re-added by the event call-back or through some other
  47. mechanism. There is another type of timer, however, the TT_PERIODIC
  48. timer, that is not removed from the timer list. TT_PERIODIC timers
  49. are similar to TT_RELATIVE timers, in that one passes in the expire
  50. time as a relative number of seconds, but when they expire, they are
  51. re-added to the timer list with the same relative expire time. This
  52. means that a TT_PERIODIC timer with an expire time of 5 seconds that
  53. is set at 11:50:00 will have its call-back called at 11:50:05,
  54. 11:50:10, 11:50:15, and so on.
  55. Timers have to be run by the event engines explicitly by calling
  56. timer_run() on the generator list passed to the engine event loop.
  57. In addition, engines may determine the next (absolute) time that a
  58. timer needs to be run by calling the timer_next() macro; this may be
  59. used to set a timeout on the engine's network activity monitoring
  60. function. Engines are described in detail below.
  61. When a timer expires, an event of ET_EXPIRE is generated, and the
  62. call-back function is called. When a timer is destroyed, either as
  63. the result of an expiration or as a result of an explicit timer_del()
  64. call, an event of ET_DESTROY is generated, notifying the call-back
  65. that the struct Timer can be deallocated.
  66. Sockets
  67. Perhaps the most complicated event generator in all of the event
  68. system is the socket, as described by struct Socket. This single
  69. classification covers datagram sockets and stream sockets. To
  70. differentiate the different kinds of sockets, there is a socket state
  71. associated with each socket. The available states are SS_CONNECTING,
  72. which indicates that a particular socket is in the process of
  73. completing a non-blocking connect(); SS_LISTENING, which indicates
  74. that a particular socket is a listening socket; SS_CONNECTED, which is
  75. the state of every other stream socket; SS_DATAGRAM, which is an
  76. ordinary datagram socket, and SS_CONNECTDG, which describes a
  77. connected datagram socket. (The SS_NOTSOCK state is for the internal
  78. use of the events system and will not be described here.)
  79. In addition to the socket states, there's also an event mask for each
  80. socket; this set of flags is used to tell the events subsystem what
  81. events the application is interested in for the socket. For
  82. SS_CONNECTING and SS_LISTENING sockets, this events mask has no
  83. meaning, but on the other socket states, the event mask is used to
  84. determine if the application is interested in readable
  85. (SOCK_EVENT_READABLE) or writable (SOCK_EVENT_WRITABLE) indications.
  86. Most of the defined event types have to do with socket generators.
  87. When a socket turns up readable, for instance, an event of type
  88. ET_READ is generated. Similarly, ET_WRITE is generated when a socket
  89. can be written to. The ET_ACCEPT event is generated when a listening
  90. socket indicates that there is a connection to be accepted; ET_CONNECT
  91. is generated when a non-blocking connect is completed. Finally, if an
  92. end-of-file indication is detected, ET_EOF is generated, whereas if an
  93. error has occurred on the socket, ET_ERROR is generated. Of course,
  94. when a socket has been deleted by the socket_del() function, an event
  95. of ET_DESTROY is generated when it is safe for the memory used by the
  96. struct Socket to be reclaimed.
  97. Events
  98. An event, represented by a struct Event, describes in detail all of
  99. the particulars of an event. Each event has a type, and an optional
  100. integer piece of data may be passed with some events--in particular,
  101. ET_SIGNAL events pass the signal number, and ET_ERROR events pass the
  102. errno value. The struct Event also contains a pointer to the
  103. structure describing the generated event--although it should be noted
  104. that the only way to disambiguate which type of generator is contained
  105. within the struct Event is by which call-back function has been
  106. called.
  107. All generators have a void pointer which can be used to pass important
  108. information to the call-back, such as a pointer to a struct Client.
  109. Additionally, generators have a reference count, and a union of a void
  110. pointer and an integer that should only be utilized by the event
  111. engine. Finally, there is also a field for flags, although the only
  112. flag of concern to the application (or the engine) is the active flag,
  113. which may be tested using the test macros described below.
  114. Whatever the generator, the call-back function is a function returning
  115. nothing (void) and taking as its sole argument a pointer to struct
  116. Event. This call-back function may be implemented as a single switch
  117. statement that calls out to appropriate external functions as needed.
  118. Engines
  119. Engines implement the actual socket event loop, and may also have some
  120. means of receiving signal events. Each engine has a name, which
  121. should describe what its core function is; for instance, the engine
  122. based on the standard select() function is named, simply, "select()."
  123. Each engine must implement several call-backs which are used to
  124. initialize the engine, notify the engine of sockets the application is
  125. interested in, etc. All of this data is described by a single struct
  126. Engine, which should be the only non-static variable or function in
  127. the engine's source file.
  128. The engine's event loop, pointed to by the eng_loop field of the
  129. struct Engine, must consist of a single while loop predicated on the
  130. global variable _running_. Additionally, this loop's final statement
  131. must be a call to timer_run(), to execute all timers that have become
  132. due. Ideally, this construction should be pulled out of each engine's
  133. eng_loop and put in the event_loop() function of the events
  134. subsystem.
  135. Reference Counts
  136. As mentioned previously, all generators keep a reference count.
  137. Should timer_del() or socket_del() be called on a generator with a
  138. non-zero reference count, for whatever reason, the actual destruction
  139. of the generator will be delayed until the reference count again
  140. reaches zero. This is used by the event loop to keep sockets that it
  141. is currently referencing from being deallocated before it is done
  142. checking all pending events on them. To increment the reference count
  143. by one, call gen_ref_inc() on the generator; the corresponding macro
  144. gen_ref_dec() decrements the reference counts, and will automatically
  145. destroy the generator if the appropriate conditions are met.
  146. Debugging Functions
  147. It can be difficult to debug an engines if, say, a socket state can
  148. only be expressed as a meaningless number. Therefore, when DEBUGMODE
  149. is #define'd, five number-to-name functions are also defined to make
  150. the debugging data more meaningful. These functions must only be
  151. called when DEBUGMODE is #define'd. Calling them from within Debug()
  152. macro calls is safe; calling them from log_write() calls is not.
  153. <typedef>
  154. typedef void (*EventCallBack)(struct Event*);
  155. The _EventCallBack_ type is used to simplify declaration of event
  156. call-back functions. It is used in timer_add(), signal_add(), and
  157. socket_add(). The event call-back should process the event, taking
  158. whatever actions are necessary. The function should be declared as
  159. returning void.
  160. </typedef>
  161. <typedef>
  162. typedef int (*EngineInit)(int);
  163. The _EngineInit_ function takes an integer specifying the maximum
  164. number of sockets the event system is expecting to handle. This
  165. number may be used by the engine initialization function for memory
  166. allocation computations. If initialization succeeds, this function
  167. must return 1. If initialization fails, the function should clean up
  168. after itself and return 0. The events subsystem has the ability to
  169. fall back upon another engine, should an engine initialization fail.
  170. Needless to say, the engines based upon poll() and select() should
  171. never fail in this way.
  172. </typedef>
  173. <typedef>
  174. typedef void (*EngineSignal)(struct Signal*);
  175. If an engine has the capability to directly detect signals, it should
  176. set the eng_signal field of struct Engine non-zero. When the
  177. application indicates interest in a particular signal, the
  178. _EngineSignal_ function will be called with the filled-in struct
  179. Signal, in order to register interest in that signal with the engine.
  180. </typedef>
  181. <typedef>
  182. typedef int (*EngineAdd)(struct Socket*);
  183. All engines must define an _EngineAdd_ function, which is used to
  184. inform the engine of the application's interest in the socket. If the
  185. new socket cannot be accommodated by the engine for whatever reason,
  186. this function must return 0. Otherwise, the function must return 1,
  187. informing the events subsystem that the interest has been noted.
  188. </typedef>
  189. <typedef>
  190. typedef void (*EngineState)(struct Socket*, enum SocketState new_state);
  191. Sockets can change state. SS_CONNECTING sockets, for instance, can
  192. become SS_CONNECTED. Whenever a socket state changes, the engine is
  193. informed, since some states require different notification procedures
  194. than others. This is accomplished by calling the _EngineState_
  195. function with the new state. The struct Socket passed to the engine
  196. will still have the old state, if the engine must reference that.
  197. </typedef>
  198. <typedef>
  199. typedef void (*EngineEvents)(struct Socket*, unsigned int new_events);
  200. Applications may only be interested in given events on a socket for a
  201. limited time. When the application's interest shifts, a new events
  202. mask is set for the socket. The engine is informed of this change by
  203. a call to its _EngineEvents_ function.
  204. </typedef>
  205. <typedef>
  206. typedef void (*EngineDelete)(struct Socket*);
  207. Eventually, an application will close all the sockets it has opened.
  208. When a socket is closed, and the corresponding struct Socket deleted
  209. with a call to socket_del(), the _EngineDelete_ function will be
  210. called to notify the engine of the change.
  211. </typedef>
  212. <typedef>
  213. typedef void (*EngineLoop)(struct Generators*);
  214. The workhorse of the entire events subsystem is the event loop,
  215. implemented by each engine as the _EngineLoop_ function. This
  216. function is called with a single argument that may be passed to
  217. timer_next() to calculate the next time a timer will expire.
  218. </typedef>
  219. <enum>
  220. enum SocketState {
  221. SS_CONNECTING, /* Connection in progress on socket */
  222. SS_LISTENING, /* Socket is a listening socket */
  223. SS_CONNECTED, /* Socket is a connected socket */
  224. SS_DATAGRAM, /* Socket is a datagram socket */
  225. SS_CONNECTDG, /* Socket is a connected datagram socket */
  226. SS_NOTSOCK /* Socket isn't a socket at all */
  227. };
  228. This enumeration contains a list of all possible states a socket can
  229. be in. Applications should not use SS_NOTSOCK; engines should treat
  230. it as a special socket state for non-sockets. The only event that
  231. should be watched for on a struct Socket in the SS_NOTSOCK state is
  232. readability. This socket state is used to implement the fall-back
  233. signal event generation.
  234. </enum>
  235. <enum>
  236. enum TimerType {
  237. TT_ABSOLUTE, /* timer that runs at a specific time */
  238. TT_RELATIVE, /* timer that runs so many seconds in the future */
  239. TT_PERIODIC /* timer that runs periodically */
  240. };
  241. The three possible timer types are defined by the TimerType
  242. enumeration. More details can be found in the "Timers" sub-section.
  243. </enum>
  244. <enum>
  245. enum EventType {
  246. ET_READ, /* Readable event detected */
  247. ET_WRITE, /* Writable event detected */
  248. ET_ACCEPT, /* Connection can be accepted */
  249. ET_CONNECT, /* Connection completed */
  250. ET_EOF, /* End-of-file on connection */
  251. ET_ERROR, /* Error condition detected */
  252. ET_SIGNAL, /* A signal was received */
  253. ET_EXPIRE, /* A timer expired */
  254. ET_DESTROY /* The generator is being destroyed */
  255. };
  256. This enumeration contains all the types of events that can be
  257. generated by the events subsystem. The first 6 are generated by
  258. socket generators, the next by signal generators, and the next by
  259. timer generators. ET_DESTROY is generated by both socket and timer
  260. generators when the events subsystem is finished with the memory
  261. allocated by both.
  262. </enum>
  263. <struct>
  264. struct Socket;
  265. This structure describes everything the events subsystem knows about a
  266. given socket. All of its fields may be accessed through the s_*
  267. macros described below.
  268. </struct>
  269. <struct>
  270. struct Timer;
  271. The struct Timer structure describes everything the events subsystem
  272. knows about a given timer. Again, all of its fields may be accessed
  273. through the t_* macros described below.
  274. </struct>
  275. <struct>
  276. struct Signal;
  277. Signal generators are described by a struct Signal. All of the fields
  278. of a struct Signal may be accessed by the sig_* macros described
  279. below.
  280. </struct>
  281. <struct>
  282. struct Event;
  283. Each event is described by a struct Event. Its fields may be examined
  284. using the ev_* macros described below.
  285. </struct>
  286. <struct>
  287. struct Generators;
  288. Each engine is passed a list of all generators when the engine's
  289. _EngineLoop_ function is called. The only valid way to access this
  290. structure is via the timer_next() function described below.
  291. </struct>
  292. <struct>
  293. struct Engine {
  294. const char* eng_name; /* a name for the engine */
  295. EngineInit eng_init; /* initialize engine */
  296. EngineSignal eng_signal; /* express interest in a signal */
  297. EngineAdd eng_add; /* express interest in a socket */
  298. EngineState eng_state; /* mention a change in state to engine */
  299. EngineEvents eng_events; /* express interest in socket events */
  300. EngineDelete eng_closing; /* socket is being closed */
  301. EngineLoop eng_loop; /* actual event loop */
  302. };
  303. Each engine is described by the struct Engine structure. Each engine
  304. must define all of the functions described above except for the
  305. _EngineSignal_ function, which is optional.
  306. </struct>
  307. <macro>
  308. #define SOCK_EVENT_READABLE 0x0001 /* interested in readable */
  309. The SOCK_EVENT_READABLE flag indicates to the engine that the
  310. application is interested in readability on this particular socket.
  311. </macro>
  312. <macro>
  313. #define SOCK_EVENT_WRITABLE 0x0002 /* interested in writable */
  314. The SOCK_EVENT_WRITABLE flag indicates to the engine that the
  315. application is interested in this socket being writable.
  316. </macro>
  317. <macro>
  318. #define SOCK_EVENT_MASK (SOCK_EVENT_READABLE | SOCK_EVENT_WRITABLE)
  319. SOCK_EVENT_MASK may be used to extract only the event interest flags
  320. from an event interest set.
  321. </macro>
  322. <macro>
  323. #define SOCK_ACTION_SET 0x0000 /* set interest set as follows */
  324. When socket_events() is called with a set of event interest flags and
  325. SOCK_ACTION_SET, the socket's event interest flags are set to those
  326. passed into socket_events().
  327. </macro>
  328. <macro>
  329. #define SOCK_ACTION_ADD 0x1000 /* add to interest set */
  330. When SOCK_ACTION_ADD is used in a call to socket_events(), the event
  331. interest flags passed in are added to the existing event interest
  332. flags for the socket.
  333. </macro>
  334. <macro>
  335. #define SOCK_ACTION_DEL 0x2000 /* remove from interest set */
  336. When SOCK_ACTION_DEL is used in a call to socket_events(), the event
  337. interest flags passed in are removed from the existing event interest
  338. flags for the socket.
  339. </macro>
  340. <macro>
  341. #define SOCK_ACTION_MASK 0x3000 /* mask out the actions */
  342. SOCK_ACTION_MASK is used to isolate the socket action desired.
  343. </macro>
  344. <function>
  345. enum SocketState s_state(struct Socket* sock);
  346. This macro returns the state of the given socket.
  347. </function>
  348. <function>
  349. unsigned int s_events(struct Socket* sock);
  350. This macro returns the current event interest mask for a given
  351. socket. Note that if the socket is in the SS_CONNECTING or
  352. SS_LISTENING states, this mask has no meaning.
  353. </function>
  354. <function>
  355. int s_fd(struct Socket* sock);
  356. This macro simply returns the file descriptor for the given socket.
  357. </function>
  358. <function>
  359. void* s_data(struct Socket* sock);
  360. When a struct Socket is initialized, data that the call-back function
  361. may find useful, such as a pointer to a struct Connection, is stored
  362. in the struct Socket. This macro returns that pointer.
  363. </function>
  364. <function>
  365. int s_ed_int(struct Socket* sock);
  366. Engines may find it convenient to associate an integer with a struct
  367. Socket. This macro may be used to retrieve that integer or, when used
  368. as an lvalue, to assign a value to it. Engine data must be either an
  369. int or a void*; use of both is prohibited.
  370. </function>
  371. <function>
  372. void* s_ed_ptr(struct Socket* sock);
  373. Engines may find it convenient to associate a void* pointer with a
  374. struct Socket. This macro may be used to retrieve that pointer or,
  375. when used as an lvalue, to assign a value to it. Engine data must be
  376. either an int or a void*; use of both is prohibited.
  377. </function>
  378. <function>
  379. int s_active(struct Socket* sock);
  380. A socket's active flag is set when initialized by socket_add(), and is
  381. cleared immediately prior to generating an event of type ET_DESTROY.
  382. This may be used by the application to determine whether or not the
  383. socket is still in use by the events subsystem. If it is, s_active()
  384. returns a non-zero value; otherwise, its value is 0.
  385. </function>
  386. <function>
  387. int socket_add(struct Socket* sock, EventCallBack call, void* data,
  388. enum SocketState state, unsigned int events, int fd);
  389. This function is called to add a socket to the list of sockets to be
  390. monitored. The _sock_ parameter is a pointer to a struct Socket that
  391. is allocated by the application. The _call_ parameter is a pointer to
  392. a function to process any events on the socket. The _data_ parameter
  393. is for use of the socket call-back and may be zero. The _state_
  394. parameter must be one of the valid socket states. The _events_
  395. parameter must be a valid events interest mask--0, or the binary OR of
  396. SOCK_EVENT_READABLE or SOCK_EVENT_WRITABLE. Finally, the _fd_
  397. parameter specifies the socket's file descriptor. This function
  398. returns 1 if successful or 0 otherwise.
  399. </function>
  400. <function>
  401. void socket_del(struct Socket* sock);
  402. When the application is no longer interested in a particular socket,
  403. it should call the socket_del() function. This function must be
  404. called no later than when the socket has been closed, to avoid
  405. attempting to call select() or similar functions on closed sockets.
  406. </function>
  407. <function>
  408. void socket_state(struct Socket* sock, enum SocketState state);
  409. Occasionally, a socket's state will change. This function is used to
  410. inform the events subsystem of that change. Only certain state
  411. transitions are valid--a socket in the SS_LISTENING or SS_CONNECTED
  412. states cannot change states, nor can an SS_CONNECTING socket change to
  413. some state other than SS_CONNECTED. Of course, SS_DATAGRAM sockets
  414. may change state only to SS_CONNECTDG, and SS_CONNECTDG sockets may
  415. only change states to SS_DATAGRAM.
  416. </function>
  417. <function>
  418. void socket_events(struct Socket* sock, unsigned int events);
  419. When the application changes the events it is interested in, it uses
  420. socket_events() to notify the events subsystem of that change. The
  421. _events_ parameter is the binary OR of one of SOCK_ACTION_SET,
  422. SOCK_ACTION_ADD, or SOCK_ACTION_DEL with an events mask. See the
  423. documentation for the SOCK_* macros for more information.
  424. </function>
  425. <function>
  426. const char* state_to_name(enum SocketState state);
  427. This function is defined only when DEBUGMODE is #define'd. It takes
  428. the given _state_ and returns a string giving that state's name. This
  429. function may safely be called from Debug() macros.
  430. </function>
  431. <function>
  432. const char* sock_flags(unsigned int flags);
  433. This function is defined only when DEBUGMODE is #define'd. It takes
  434. the given event interest flags and returns a string naming each of
  435. those flags. This function may safely be called from Debug() macros,
  436. but may only be called once, since it uses function static storage to
  437. store the flag strings.
  438. </function>
  439. <function>
  440. int sig_signal(struct Signal* sig);
  441. This macro returns the signal number for the given struct Signal.
  442. </function>
  443. <function>
  444. void* sig_data(struct Signal* sig);
  445. When a struct Signal is initialized, data that the call-back function
  446. may find useful is stored in the struct Signal. This macro returns
  447. that pointer.
  448. </function>
  449. <function>
  450. int sig_ed_int(struct Signal* sig);
  451. Engines may find it convenient to associate an integer with a struct
  452. Signal. This macro may be used to retrieve that integer or, when used
  453. as an lvalue, to assign a value to it. Engine data must be either an
  454. int or a void*; use of both is prohibited.
  455. </function>
  456. <function>
  457. void* sig_ed_ptr(struct Signal* sig);
  458. Engines may find it convenient to associate a void* pointer with a
  459. struct Signal. This macro may be used to retrieve that pointer or,
  460. when used as an lvalue, to assign a value to it. Engine data must be
  461. either an int or a void*; use of both is prohibited.
  462. </function>
  463. <function>
  464. int sig_active(struct Signal* sig);
  465. A signal's active flag is set when initialized by signal_add(). This
  466. may be used by the application to determine whether or not the signal
  467. has been initialized yet. If it is, sig_active() returns a non-zero
  468. value; otherwise, its value is 0.
  469. </function>
  470. <function>
  471. void signal_add(struct Signal* signal, EventCallBack call, void* data,
  472. int sig);
  473. This function is called to add a signal to the list of signals to be
  474. monitored. The _signal_ parameter is a pointer is a pointer to a
  475. struct Signal that is allocated by the application. The _call_
  476. parameter is a pointer to a function to process any signal events.
  477. The _data_ parameter is for use of the signal call-back and may be
  478. zero. The _sig_ parameter is the integer value of the signal to be
  479. monitored.
  480. </function>
  481. <function>
  482. enum TimerType t_type(struct Timer* tim);
  483. This macro returns the type of the given timer.
  484. </function>
  485. <function>
  486. time_t t_value(struct Timer* tim);
  487. This macro returns the value that was used when the given timer was
  488. initialized by the events subsystem. It will contain an absolute time
  489. if the timer type is TT_ABSOLUTE, and a relative time otherwise.
  490. </function>
  491. <function>
  492. time_t t_expire(struct Timer* tim);
  493. This macro returns the absolute time at which the timer will next
  494. expire.
  495. </function>
  496. <function>
  497. void* t_data(struct Timer* tim);
  498. When a struct Timer is initialized, data that the call-back function
  499. may find useful is stored in the struct Socket. This macro returns
  500. that pointer.
  501. </function>
  502. <function>
  503. int t_ed_int(struct Timer *tim);
  504. Engines may find it convenient to associate an integer with a struct
  505. Timer. This macro may be used to retrieve that integer or, when used
  506. as an lvalue, to assign a value to it. Engine data must be either an
  507. int or a void*; use of both is prohibited.
  508. </function>
  509. <function>
  510. void* t_ed_ptr(struct Timer *tim);
  511. Engines may find it convenient to associate a void* pointer with a
  512. struct Timer. This macro may be used to retrieve that pointer or,
  513. when used as an lvalue, to assign a value to it. Engine data must be
  514. either an int or a void*; use of both is prohibited.
  515. </function>
  516. <function>
  517. int t_active(struct Timer *tim);
  518. A timer's active flag is set when initialized by timer_add(), and is
  519. cleared immediately prior to generating an event of type ET_DESTROY.
  520. This may be used by the application to determine whether or not the
  521. timer is still in use by the events subsystem. If it is, s_active()
  522. returns a non-zero value; otherwise, its value is 0.
  523. </function>
  524. <function>
  525. void timer_add(struct Timer* timer, EventCallBack call, void* data,
  526. enum TimerType type, time_t value);
  527. This function is called to initialize and queue a timer. The _timer_
  528. parameter is a pointer to a struct Timer that is allocated by the
  529. application. The _call_ parameter is a pointer to a function to
  530. process the timer's expiration. The _data_ parameter is for use of
  531. the timer call-back and may be zero. The _type_ parameter must be one
  532. of the valid timer types--TT_ABSOLUTE, TT_RELATIVE, or TT_PERIODIC.
  533. Finally, _value_ is the value for the timer's expiration.
  534. </function>
  535. <function>
  536. void timer_del(struct Timer* timer);
  537. When the application no longer needs a TT_PERIODIC timer, or when it
  538. wishes to stop a TT_ABSOLUTE or TT_RELATIVE timer before its
  539. expiration, it should call the timer_del() function.
  540. </function>
  541. <function>
  542. void timer_chg(struct Timer* timer, enum TimerType type, time_t value);
  543. Occasionally, an application may wish to delay an existing TT_ABSOLUTE
  544. or TT_RELATIVE timer; this may be done with the timer_chg() function.
  545. The _type_ parameter must be one of TT_ABSOLUTE or
  546. TT_RELATIVE--changing the values of TT_PERIODIC timers is not
  547. supported. The _value_ parameter is the same as would be given to
  548. timer_add() for that particular type of timer.
  549. </function>
  550. <function>
  551. void timer_run(void);
  552. When an engine has finished processing the results of its socket and
  553. signal checks--just before it loops around to test for more events--it
  554. should call the timer_run() function to expire any waiting timers.
  555. </function>
  556. <function>
  557. time_t timer_next(struct Generators* gen);
  558. Most engines will use a blocking call with a timeout to check for
  559. socket activity. To determine when the next timer needs to be run,
  560. and thus to calculate how long the call should block, the engine
  561. should call timer_next() with the _gen_ parameter passed to the
  562. _EngineLoop_ function. The timer_next() function returns an absolute
  563. time, which may have to be massaged into a relative time before the
  564. engine may use it.
  565. </function>
  566. <function>
  567. const char* timer_to_name(enum TimerType type);
  568. This function is defined only when DEBUGMODE is #define'd. It takes
  569. the given _type_ and returns a string giving that type's name. This
  570. function may safely be called from Debug() macros.
  571. </function>
  572. <function>
  573. enum EventType ev_type(struct Event* ev);
  574. This macro simply returns the type of the event _ev_.
  575. </function>
  576. <function>
  577. int ev_data(struct Event* ev);
  578. When an event is generated, a single integer can be passed along as a
  579. piece of extra information. This can be used, for instance, to carry
  580. an errno value when an ET_ERROR is generated. This macro simply
  581. returns that integer.
  582. </function>
  583. <function>
  584. struct Socket* ev_socket(struct Event* ev);
  585. If the event was generated by a socket, this macro returns a pointer
  586. to the struct Socket that generated the event. The results are
  587. undefined if the event was not generated by a socket.
  588. </function>
  589. <function>
  590. struct Signal* ev_signal(struct Event* ev);
  591. If the event was generated by a signal, this macro returns a pointer
  592. to the struct Signal that generated the event. The results are
  593. undefined if the event was not generated by a signal.
  594. </function>
  595. <function>
  596. struct Timer* ev_timer(struct Event* ev);
  597. If the event was generated by a timer, this macro returns a pointer to
  598. the struct Timer that generated the event. The results are undefined
  599. if the event was not generated by a timer.
  600. </function>
  601. <function>
  602. void event_init(int max_sockets);
  603. Before any of the functions or macros described here can be called,
  604. the events subsystem must be initialized by calling event_init(). The
  605. _max_sockets_ parameter specifies to the events subsystem how many
  606. sockets it must be able to support; this figure may be used for memory
  607. allocation by the engines.
  608. </function>
  609. <function>
  610. void event_loop(void);
  611. Once the initial sockets are open, signals added, and timers queued,
  612. the application must call the event_loop() function in order to
  613. actually begin monitoring those sockets, signals, and timers.
  614. </function>
  615. <function>
  616. void event_generate(enum EventType type, void* arg, int data);
  617. This is the function called by the events subsystem to generate
  618. particular events. The _type_ parameter specifies the type of event
  619. to generate, and the _arg_ parameter must be a pointer to the event's
  620. generator. The _data_ parameter may be used for passing such things
  621. as signal numbers or errno values.
  622. </function>
  623. <function>
  624. const char* event_to_name(enum EventType type);
  625. This function is defined only when DEBUGMODE is #define'd. It takes
  626. the given _type_ and returns a string giving that event type's name.
  627. This function may safely be called from Debug() macros.
  628. </function>
  629. <function>
  630. const char* engine_name(void);
  631. This function is used to retrieve the name of the engine presently
  632. being used by the events subsystem.
  633. </function>
  634. <function>
  635. void gen_ref_inc(void* gen);
  636. This macro increments the reference count of the generator _gen_,
  637. preventing it from simply disappearing without warning.
  638. </function>
  639. <function>
  640. void gen_ref_dec(void* gen);
  641. This macro decrements the reference count of the generator _gen_, and
  642. releases the memory associated with it by generating at ET_DESTROY
  643. event if the reference count falls to zero and the generator is marked
  644. for destruction. No references should be made to the generator after
  645. calling this macro.
  646. </function>
  647. <authors>
  648. Kev <klmitch@mit.edu>
  649. </authors>
  650. <changelog>
  651. [2001-6-14 Kev] Finished initial description of the events subsystem.
  652. [2001-6-13 Kev] Initial description of the events subsystem.
  653. </changelog>