Class Ioloop
This class contains the ioloop implementation.
In short: allowing you to work with several MQTT clients in one script, and allowing them to maintain a long-term connection to broker, using PINGs. This is the bundled alternative to Copas and Nginx.
NOTE: this module will work only with MQTT clients using the connector.luasocket connector.
Providing an IO loop instance dealing with efficient (as much as possible in limited lua IO) network communication for several MQTT clients in the same OS thread. The main idea is that you are creating an ioloop instance, then adding MQTT clients to it. Then ioloop is starting an endless loop trying to receive/send data for all added MQTT clients. You may add more or remove some MQTT clients to/from the ioloop after it has been created and started.
Using an ioloop is allowing you to run a MQTT client for long time, through sending PINGREQ packets to broker in keepAlive interval to maintain long-term connection.
Also, any function can be added to the ioloop instance, and it will be called in the same endless loop over and over alongside with added MQTT clients to provide you a piece of processor time to run your own logic (like running your own network communications or any other thing good working in an io-loop)
Metamethods
ioloop:__init (opts) | Initialize ioloop instance. |
Methods
ioloop:add (client) | Add MQTT client or a loop function to the ioloop instance. |
ioloop:remove (client) | Remove MQTT client or a loop function from the ioloop instance |
ioloop:iteration () | Perform one ioloop iteration. |
ioloop:run_until_clients () | Run the ioloop. |
Exported functions
ioloop.create () | Create IO loop instance with given options |
ioloop.get ([autocreate=true[, opts]]) | Returns default ioloop instance |
Metamethods
- ioloop:__init (opts)
-
Initialize ioloop instance.
Parameters:
- opts ioloop creation options table
- sleep_min number min sleep interval after each iteration (default 0)
- sleep_step number increase in sleep after every idle iteration (default 0.002)
- sleep_max number max sleep interval after each iteration (default 0.030)
- sleep_function function custom sleep function to call after each iteration (default luasocket.sleep)
Returns:
-
Ioloop
ioloop instance
- opts ioloop creation options table
Methods
- ioloop:add (client)
-
Add MQTT client or a loop function to the ioloop instance.
When adding a function, the function should on each call return the time (in seconds) it wishes to sleep. The ioloop
will sleep after each iteration based on what clients/functions returned. So the function may be called sooner than
the requested time, but will not be called later.
Parameters:
- client client_mt or function MQTT client or a loop function to add to ioloop
Returns:
-
true on success or false and error message on failure
Usage:
-- create a timer on a 1 second interval local timer do local interval = 1 local next_call = socket.gettime() + interval timer = function() if next_call >= socket.gettime() then -- do stuff here next_call = socket.gettime() + interval return interval else return next_call - socket.gettime() end end end loop:add(timer)
- ioloop:remove (client)
-
Remove MQTT client or a loop function from the ioloop instance
Parameters:
- client client_mt or function MQTT client or a loop function to remove from ioloop
Returns:
-
true on success or false and error message on failure
- ioloop:iteration ()
- Perform one ioloop iteration. TODO: make this smarter do not wake-up functions or clients returning a longer sleep delay. Currently they will be tried earlier if another returns a smaller delay.
- ioloop:run_until_clients ()
- Run the ioloop. While there is at least one client/function in the ioloop it will continue iterating. After all clients/functions are gone, it will return.
Exported functions
- ioloop.create ()
-
Create IO loop instance with given options
Returns:
-
Ioloop
ioloop instance
See also:
- ioloop.get ([autocreate=true[, opts]])
-
Returns default ioloop instance
Parameters:
- autocreate boolean Automatically create ioloop instance (default true)
- opts table Arguments for creating ioloop instance (optional)
Returns:
-
Ioloop
ioloop instance