Async

The Async functions are used to asynchronously run code.

• Timer
• Thread

New in version 8.1.5.

• Event

Timer

A timer is used to schedule (repeated) callbacks to be called in the future.

API

userdata pilight.async.timer()

Creates a new timer object

Changed in version nightly.

userdata pilight.async.timer([userdata timer instance])

Creates a new timer object or restore the saved instance when passing the instance parameter.

New in version nightly.

userdata pilight.async.timer()()

Returns the timer instance as lightuserdata so it can be stored in a pilight metatable.

userdata getUserdata()

Returns a persistent userdata table for the lifetime of the timer object.

boolean setCallback(string callback)

The name of the callback being triggered by the timer. The timer object will be passed as the only parameter of this callback function.

boolean setUserdata(userdata table)

Set a new persistent userdata table for the lifetime of the timer object. The userdata table cannot be of another type as returned from the getUserdata functions.

boolean setRepeat(numeric millisecond)

If repeat is non-zero, the callback fires first after the milliseconds set and then repeatedly after repeat milliseconds.

boolean setTimeout(numeric millisecond)

If timeout is zero, the timer is fired as soon as possible. If the timer is non-zero, the callback will be fired after the milliseconds set.

boolean start()

Start the timer

boolean stop()

Stops the timer

Example

local M = {};

function M.timer(timer)
  local data = timer.getUserdata();
  print(data['msg']);

  timer.stop();
end

function M.run()
  local timer = pilight.async.timer();
  local data = timer.getUserdata();

  data['status'] = "Hello World!";

  timer.setCallback("timer");
  timer.setTimeout(1000);
  timer.setRepeat(1000);
  timer.start();

  return 1;
end

return M;

Thread

A thread can be used to trigger a callbacks concurrently.

API

userdata pilight.async.thread()

Creates a new thread object

Changed in version nightly.

userdata pilight.async.thread([userdata thread instance])

Creates a new thread object or restore the saved instance when passing the instance parameter.

New in version nightly.

userdata pilight.async.thread()()

Returns the thread instance as lightuserdata so it can be stored in a pilight metatable.

userdata getUserdata()

Returns a persistent userdata table for the lifetime of the thread object.

boolean setCallback(string callback)

The name of the callback being triggered by the thread. The thread object will be passed as the only parameter of this callback function.

boolean setUserdata(userdata table)

Set a new persistent userdata table for the lifetime of the thread object. The userdata table cannot be of another type as returned from the getUserdata functions.

boolean trigger()

Trigger the thread callback

Example

local M = {};

function M.thread(thread)
  local data = thread.getUserdata();

  print(data['status']);
end

function M.run()
  local thread = pilight.async.thread();
  local data = thread.getUserdata();

  thread.setCallback("thread");

  data['status'] = "Hello World!";

  thread.trigger();

  return 1;
end

return M;

Event

New in version 8.1.5.

The event library implements an async consumer listener pattern

API

userdata pilight.async.event()

Creates a new event object

Changed in version nightly.

userdata pilight.async.event([userdata event instance])

Creates a new event object or restore the saved instance when passing the instance parameter.

New in version nightly.

userdata pilight.async.event()()

Returns the event instance as lightuserdata so it can be stored in a pilight metatable.

userdata register(int callback)

Register the async object to a specific event

userdata unregister(int callback)

Unregister the async object from a specific event

userdata getUserdata()

Returns a persistent userdata table for the lifetime of the thread object.

boolean setCallback(string callback)

The name of the callback being trigger when the event occured

boolean setUserdata(userdata table)

Set a new persistent userdata table for the lifetime of the thread object. The userdata table cannot be of another type as returned from the getUserdata functions.

boolean trigger(userdata table)

Trigger an event with data from lua

boolean gc()

Garbage collect the event object when no callback is set

Example listening

local M = {};

function M.send(event, reason, data)
  --
  -- Check, double check
  --
  if reason ~= pilight.reason.SEND_CODE then
     return;
  end;

  print(data['pulses']); -- The SEND_CODE metatable contains specific keys like 'pulses'
end

function M.run()
  local event = pilight.async.event();
  event.register(pilight.reason.SEND_CODE);
  event.setCallback("event");

  return 1;
end

return M;

Example triggering

local M = {};

function M.run()
  local event = pilight.async.event();
  event.register(pilight.reason.RECEIVED_PULSETRAIN);

  local data = {};
  data['length'] = 0;

  event.trigger(data)
  event.gc();

  return 1;
end

return M;