Tue, 20 Nov 2007 18:03:53 -0500
docs: Added remaining documentation for luaevent.core
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
1 | ---- |
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
2 | Constants: |
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
3 | |
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
4 | * `LEAVE` - When returned will cause event callback to be cancelled |
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
5 | * `EV_READ` |
51
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
6 | * Marks read readiness/event capture. |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
7 | * Read readiness can also mean that an 'accept' operation will succeed, or |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
8 | a disconnection on the other end is detected (read will return nothing). |
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
9 | * `EV_WRITE` |
51
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
10 | * Marks write readiness/event capture. |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
11 | * Can also mark the successful completion of a non-blocking connect |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
12 | if `SO_ERROR`@`SOL_SOCKET` is zero. |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
13 | * `EV_SIGNAL` |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
14 | * Marks signal received/event capture |
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
15 | * `EV_TIMEOUT` |
51
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
16 | * Timeout occurred while waiting for an event |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
17 | * `EV_PERSIST` |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
18 | * Marks an event as persistent and not one-shot |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
19 | * `EV_*` |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
20 | * Can be OR'd together to capture multiple events that make sense. |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
21 | (Should not OR `EV_READ`/`EV_WRITE` with `EV_SIGNAL`) |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
22 | * Can be received OR'd together. |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
23 | For example: `EV_READ` | `EV_TIMEOUT` means that a timeout |
a11824050314
doc: Update luaevent.core to contain docs on EV_* values
Thomas Harning Jr <harningt@gmail.com>
parents:
48
diff
changeset
|
24 | occurred while waiting for a read event. |
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
25 | * `EVBUFFER_READ` |
52
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
26 | * Marks that the input buffer has data available > low watermark |
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
27 | * `EVBUFFER_WRITE` |
52
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
28 | * Marks that the output buffer level is below low watermark |
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
29 | * `EVBUFFER_EOF` |
52
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
30 | * Received tagged with either read/write based on location received in the error callback |
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
31 | * `EVBUFFER_ERROR` |
52
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
32 | * An error occurred (tagged w/ either read/write) and the error is in `errno` |
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
33 | * `EVBUFFER_TIMEOUT` |
52
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
34 | * A timeout occurred (tagged w/ either read/write) |
48
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
35 | |
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
36 | Functions: |
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
37 | |
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
38 | [[toc levels=1]] |
7e1abd8cb4e8
docs: Beginning of luaevent.core documentation
Thomas Harning Jr <harningt@gmail.com>
parents:
43
diff
changeset
|
39 | |
52
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
40 | ## luaevent.core.new |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
41 | * Allocates a new event 'core' (`event base`) |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
42 | |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
43 | ## event_callback fn |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
44 | * Input: `(event)` |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
45 | * Output: `(newEvent, [newTimeout])` |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
46 | * `newEvent` - New event to register, typically `LEAVE`, `EV_READ`, `EV_WRITE`, or `EV_READ`|`EV_WRITE` |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
47 | * `newTimeout` - New timeout value to use |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
48 | |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
49 | ## core:addevent |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
50 | * Adds a new event to the eventloop |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
51 | * Input: `(fd, event, event_callback, [timeout])` |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
52 | * `fd` - File descriptor to read from / or NIL for pure timeout event |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
53 | * `event` - `EV_*` flagset to mark what events to capture |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
54 | * `EV_SIGNAL` and `EV_PERSIST` is unavailable currently |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
55 | * `EV_PERSIST` is used internally. |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
56 | * `event_callback` - Callback to call... (see above) |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
57 | * `timeout` - Time in seconds to timeout (decimal values supported) |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
58 | * Output: `event_callback` object |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
59 | * Has a `close` and `__gc` FN which will erase the callback, |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
60 | so preserve this until done. |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
61 | |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
62 | ## core:loop |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
63 | * Begins the event loop and doesn't return until there are no events left |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
64 | |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
65 | ## core:close (__gc) |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
66 | * Closes the event base |
48def27d8ddd
docs: Added remaining documentation for luaevent.core
Thomas Harning Jr <harningt@gmail.com>
parents:
51
diff
changeset
|
67 | * Do not allow this to be called while `core:loop` is running |