aboutsummaryrefslogtreecommitdiffstats
path: root/doc/modules/luaevent.core.mdwn
blob: 6c7b1125026e58c393573d8958284b27a7d63c22 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
----
Constants:

* `LEAVE` - When returned will cause event callback to be cancelled
* `EV_READ`
	* Marks read readiness/event capture.
	* Read readiness can also mean that an 'accept' operation will succeed, or
	  a disconnection on the other end is detected (read will return nothing).
* `EV_WRITE`
	* Marks write readiness/event capture.
	* Can also mark the successful completion of a non-blocking connect
	  if `SO_ERROR`@`SOL_SOCKET` is zero.
* `EV_SIGNAL`
	* Marks signal received/event capture
* `EV_TIMEOUT`
	* Timeout occurred while waiting for an event
* `EV_PERSIST`
	* Marks an event as persistent and not one-shot
* `EV_*`
	* Can be OR'd together to capture multiple events that make sense.
	  (Should not OR `EV_READ`/`EV_WRITE` with `EV_SIGNAL`)
	* Can be received OR'd together.
	  For example: `EV_READ` | `EV_TIMEOUT` means that a timeout
	  occurred while waiting for a read event.
* `EVBUFFER_READ`
	* Marks that the input buffer has data available > low watermark
* `EVBUFFER_WRITE`
	* Marks that the output buffer level is below low watermark
* `EVBUFFER_EOF`
	* Received tagged with either read/write based on location received in the error callback
* `EVBUFFER_ERROR`
	* An error occurred (tagged w/ either read/write) and the error is in `errno`
* `EVBUFFER_TIMEOUT`
	* A timeout occurred (tagged w/ either read/write)

Functions:

[[toc levels=1]]

## luaevent.core.new
* Allocates a new event 'core' (`event base`)

## event_callback fn
* Input: `(event)`
* Output: `(newEvent, [newTimeout])`
	* `newEvent` - New event to register, typically `LEAVE`, `EV_READ`, `EV_WRITE`, or `EV_READ`|`EV_WRITE`
	* `newTimeout` - New timeout value to use

## core:addevent
* Adds a new event to the eventloop
* Input: `(fd, event, event_callback, [timeout])`
	* `fd` - File descriptor to read from / or NIL for pure timeout event
	* `event` - `EV_*` flagset to mark what events to capture
		* `EV_SIGNAL` and `EV_PERSIST` is unavailable currently
		* `EV_PERSIST` is used internally.
	* `event_callback` - Callback to call... (see above)
	* `timeout` - Time in seconds to timeout (decimal values supported)
* Output: `event_callback` object
	* Has a `close` and `__gc` FN which will erase the callback, 
	  so preserve this until done.

## core:loop
* Begins the event loop and doesn't return until there are no events left

## core:close (__gc)
* Closes the event base
* Do not allow this to be called while `core:loop` is running