Event system

4 files changed, 31 insertions, 46 deletions

diff --git a/doc/client.md b/doc/client.md
index 9c1922e..fe9fb7d 100644
--- a/doc/client.md
+++ b/doc/client.md
@@ -9,17 +9,15 @@ After being disconnect, a client cannot be reconnected.
 - `self:address()`: Returns address passed to `hydra.client` upon creation as a string.
 - `self:state()`: Returns current connection state as a string ("new", "connected", "disconnected")
 - `self:connect()`: Connects to server. Throws an error if the client is not in "new" state OR address resolution / dial fails (Note: If required, you can use `pcall` to catch and handle errors instead of crashing the script). Connection failure (= host found, but no minetest server running on port) is equivalent to an immediate disconnect and does not cause an error to be thrown.
-- `self:poll([timeout])`: Polls packets from client. See [poll.md](poll.md) for behavior and return values.
+- `self:poll([timeout])`: Polls events from client. See [poll.md](poll.md) for behavior and return values.
 - `self:close()`: Closes the network connection if in `connected` state. The client remains in `connected` state until passed to poll.
 - `self:enable(component)`: Enables the component with the name `component` (string), if not already enabled. By default, no components are enabled. See Components section.
-- `self:subscribe(pkt1, [pkt2, ...])`: Subscribes to all packet passed as arguments (strings). For available packets, see [client_pkts.md](client_pkts.md). By default, the client is not subscribed to any packets.
-- `self:unsubscribe(pkt1, [pkt2, ...])`: Unsubscribes from all packet passed as arguments (strings).
-- `self:wildcard(wildcard)`: Sets wildcard mode to `wildcard` (boolean). If wildcard is enabled, ALL packets are returned by poll, even those that the client did not subscribe to. It is not recommended to use this without a reason since converting packets to Lua costs performance and creates and overhead due to poll returning more often. `wildcard` is unnecessary if only certain packets are handled anyway, but it is useful for traffic inspection and debugging.
-- `self:send(pkt_name, pkt_data, [ack])`: Sends a packet to server. Throws an error if the client is not connected. `pkt_name` is the type of the packet as string. `pkt_data` is a table containing packet parameters. Some packets don't have parameters (e.g. `respawn`) - in this case, `pkt_data` can be omitted. See [server_pkts.md](server_pkts.md) for available packets. If `ack` is true, this function will block until acknowledgement from server is received.
+- `self:send(pkt_type, pkt_data, [ack])`: Sends a packet to server. Throws an error if the client is not connected. `pkt_type` is the type of the packet as string. `pkt_data` is a table containing packet parameters. Some packets don't have parameters (e.g. `respawn`) - in this case, `pkt_data` can be omitted. See [server_pkts.md](server_pkts.md) for available packets. If `ack` is true, this function will block until acknowledgement from server is received.
 
 ## Components
 
 Enabled components can be accessed by using `self.<component name>`.
 
+- `self.pkt`: Allows you to handle selected packets yourself. Most scripts use this. See [pkts.md](pkts.md).
 - `self.auth`: Handles authentication. Recommended for the vast majority of scripts. See [auth.md](auth.md).
 - `self.map`: Stores MapBlocks received from server. See [map.md](map.md).
diff --git a/doc/hydra.md b/doc/hydra.md
index 4eac2cf..fd916e0 100644
--- a/doc/hydra.md
+++ b/doc/hydra.md
@@ -13,6 +13,5 @@ The `hydra` table contains functions necessary to handle connections.
 
 - `hydra.client(address)`: Returns a new client. Address must be a string. For client functions, see [client.md](client.md).
 - `hydra.dtime()`: Utility function that turns the elapsed time in seconds (floating point) since it was last called (or since program start).
-- `hydra.canceled()`: Utility function that returns true if the program was interrupted (SIGINT, SIGTERM, SIGHUP).
-- `hydra.poll(clients, [timeout])`: Polls subscribed packets from all clients in `clients` (table). For behavior and return value, see [poll.md](poll.md).
+- `hydra.poll(clients, [timeout])`: Polls events from all clients in `clients` (table). For behavior and return value, see [poll.md](poll.md).
 - `hydra.close(clients)`: Closes all clients in `clients` (table) that are currently connected. See `client:close()` in [client.md](client.md) for more info.
diff --git a/doc/pkts.md b/doc/pkts.md
new file mode 100644
index 0000000..fba5083
--- /dev/null
+++ b/doc/pkts.md
@@ -0,0 +1,18 @@
+# Packet Handler Component
+Source code: [pkts.go](../pkts.go)
+
+The packet handler component allows you to handle packets yourself. It fires events in the form of `{ type = "pkt", client = ..., pkt_type = "...", pkt_data = { ... } }``` when subscribed packets are received.
+For available packets, see [client_pkts.md](client_pkts.md). By default, not packets are packets subscribed.
+
+## Wildcard mode
+
+If wildcard is enabled, events for all packets are fired, even ones that are not subscribed. It is not recommended to use this without a reason since converting packets to Lua costs performance and creates and overhead due to poll returning more often. `wildcard` is unnecessary if only certain packets are handled anyway, but it is useful for traffic inspection and debugging.
+
+## Functions
+
+- `self:subscribe(pkt1, [pkt2, ...])`: Subscribes to all packet types passed as arguments (strings).
+
+- `self:unsubscribe(pkt1, [pkt2, ...])`: Unsubscribes from all packet passed as arguments (strings).
+
+- `self:wildcard(wildcard)`: Sets wildcard mode to `wildcard` (boolean).
+
diff --git a/doc/poll.md b/doc/poll.md
index 494fe48..16aa62c 100644
--- a/doc/poll.md
+++ b/doc/poll.md
@@ -1,49 +1,19 @@
 # Polling API
 Source code: [poll.go](../poll.go)
 
-**TL;DR**: poll is complex and has many different cases, but in general, it returns the received packet and the associated client; if one of the clients closes, a nil packet is returned once. client may also be nil in some cases so watch out for that.
+`poll` waits for and returns the next event from one or more clients, or `nil` if none of the clients passed to it are active (`connected` state).
+Optionally, a timeout can be passed to poll; if no other event occurs until the timeout elapses, a timeout event is returned.
 
-Together with sending, polling is the core function of hydra. It is used to receive packets from a packet queue.
+## Events
 
-For each client, only packets that the client has subscribed to are inserted into that queue, unless wildcard is enabled.
+An event is a table that contains a string `type`. Depending on the type, it may have different other fields.
 
-Packet receival from network happens asynchronously. When a packet is received and has been processed by components, it is enqueued for polling if the client is subscribed to it. **Because of the poll queue, packets may be returned by poll that the client was subscribed to in the past but unsubscribed recently.** Since the queue has a limited capacity of 1024 packets (this may change in the future), it is your responsibility to actually poll in a frequency suitable to keep up with the amount of packets you expect based on what you are subscribed to. If the queue is full, the thread responsible for receival will block.
+- `type = "interrupt"`: Fired globally when the program was interrupted using a signal.
 
-Clients that are not in `connected` state are ignored by poll.
+- `type = "timeout"`: Fired when the timeout elapses.
 
-Poll blocks until one of these conditions is met (in this order). The return value depends on which condition is met:
+- `type = "pkt"`: Fired when a packet was received. See [pkts.md](pkts.md)
 
-1. No clients are available when the function is called. This happens if either no clients were passed to poll or none of them is connected.
+- `type = "disconnect"`: Fired when a client connection closed. Has a `client` field. 
 
-2. One of the clients closes. In this case, the client that closed is set to `disconnected` state. The close may happen before or during the call to poll, but it has effect only once.
-
-3. A packet is in queue for one of the clients (Main case).
-
-4. An interrupt signal is received during polling (See `hydra.canceled`).
-
-5. The configured timeout elapses.
-
-## Different versions
-
-There is two different versions of poll: `client:poll` for polling a single client and `hydra.poll` for polling multiple clients.
-They are mostly equivalent but differ in return values and arguments:
-
-- `client:poll([timeout])` polls from the client `client` and returns `pkt, interrupted`
-
-- `hydra.poll(clients, [timeout])` takes table of clients as argument and returns `pkt, client, interrupted`
-
-## Arguments and return values
-
-The timeout argument is an optional floating point number holding the timeout in seconds, if `nil`, poll will block until one of the conditions 1.-4. are met. Timeout may be `0`, in this case poll returns immediately even if none of the other conditions are met immediately.
-
-Return values for different cases:
-
-1. If no clients are available, `nil, nil, false` (or `nil, false` respectively) is returned.
-
-2. If a client closes, `nil, client, false` (or `nil, false` respectively) is returned.
-
-3. If a packet is available, poll returns `pkt, client, false` (or `pkt, false` respectively). `pkt` is a table containing the received packet (see [client_pkts.md](client_pkts.md)) and `client` is the client reference that has received the packet.
-
-4. If the program is interrupted, poll returns `nil, nil, true` (or `nil, true` respectively).
-
-5. If the timeout elapses, poll returns `nil, nil, true` (or `nil, true` respectively).
+- `type = "error"`: Fired when an error occurs during deserialization of a packet. Has a `client` field. Stores the error message in an `error` field.