Debian Codegraph @

doc/html/_sources/imap/developer/thoughts/prot-events.rst.txt

raw
1 .. _imap-developer-thoughts-prot-events:
2
3 .. Note: This document was converted from the original by Nic Bernstein
4 (Onlight). Any formatting mistakes are my fault and not the
5 original author's. Converted via the pandoc tool from HTML.
6
7 Cyrus IMAP Server: Prot Events
8 ==============================
9
10 From an email exchange between Ken Murchison and Lawrence Greenfield,
11 dated 03 Feb 2002 (slightly redacted and formatted for your viewing
12 pleasure):
13
14 | From: Ken Murchison
15 | To: Lawrence Greenfield
16 | Subject: Re: prot events
17 |
18
19 Lawrence Greenfield wrote:
20
21 Can you give me some details on how the event API in the prot
22 layer works? I'm a little unclear about the memory management,
23 what should be returned from the event callback,
24
25 Either the event pointer (if the event is still active), or NULL
26 (if the event has been removed by the callback).
27
28 and how to reschedule an event.
29
30 Simply set the 'mark' time in the event to the wall time you want
31 it to run again.
32
33 (I'd like to make an event called every X seconds of idle time;
34 I know the API can't do exactly that but I suspect I can fake
35 it well enough.)
36
37 Look at backend_timeout() in proxyd.c and/or drac_ping() in
38 contrib/drac_auth.patch, they do exactly this.
39
40 The API is pretty simple:
41
42 * use prot_addwaitevent() to add an event (linked list) callback
43 onto a stream. takes the stream, the 'mark' time at which to
44 run the event (NOT an interval, but the future clock value),
45 the function pointer, and a rock to pass to the callback as
46 args, and returns a pointer to the event (to use for future
47 removal).
48
49 * use prot_removewaitevent() to remove an event. takes the
50 stream and a pointer to the event as args.
51
52 * the event callback gets the stream, a pointer to the event
53 and the rock as args. To reschedule an event, simply set the
54 'mark' time and return the event pointer. If the callback
55 removes the event, then return NULL.
56
57 If you see and flaws in this API, feel free to go ahead and change it.
58
59 Ken