doc/poll.md

   1 # Polling API
   2 Source code: [poll.go](../poll.go)
   3
   4 **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.
   5
   6 Together with sending, polling is the core function of hydra. It is used to receive packets from a packet queue.
   7
   8 For each client, only packets that the client has subscribed to are inserted into that queue, unless wildcard is enabled.
   9
  10 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.
  11
  12 Clients that are not in `connected` state are ignored by poll.
  13
  14 Poll blocks until one of these conditions is met (in this order). The return value depends on which condition is met:
  15
  16 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.
  17
  18 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.
  19
  20 3. A packet is in queue for one of the clients (Main case).
  21
  22 4. An interrupt signal is received during polling (See `hydra.canceled`).
  23
  24 5. The configured timeout elapses.
  25
  26 ## Different versions
  27
  28 There is two different versions of poll: `client:poll` for polling a single client and `hydra.poll` for polling multiple clients.
  29 They are mostly equivalent but differ in return values and arguments:
  30
  31 - `client:poll([timeout])` polls from the client `client` and returns `pkt, interrupted`
  32
  33 - `hydra.poll(clients, [timeout])` takes table of clients as argument and returns `pkt, client, interrupted`
  34
  35 ## Arguments and return values
  36
  37 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.
  38
  39 Return values for different cases:
  40
  41 1. If no clients are available, `nil, nil, false` (or `nil, false` respectively) is returned.
  42
  43 2. If a client closes, `nil, client, false` (or `nil, false` respectively) is returned.
  44
  45 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.
  46
  47 4. If the program is interrupted, poll returns `nil, nil, true` (or `nil, true` respectively).
  48
  49 5. If the timeout elapses, poll returns `nil, nil, true` (or `nil, true` respectively).