Lumen

• Index

Contents

• Functions
• Tables
• Fields
• Data structures

Modules

• sched
• mutex
• catalog
• pipes
• stream
• log
• shell
• selector
• proxy

Topics

• README

Examples

• test.lua
• test-selector.lua
• test-pipe.lua
• test-stress.lua
• test-pause.lua
• test-mutex.lua

Module sched

Lumen cooperative scheduler.

Lumen (Lua Multitasking Environment) is a simple environment for coroutine based multitasking. Consists of a signal scheduler, and that's it.

Usage:

local sched = require 'lumen.sched'
sched.sigrun({'a signal'}, print)
local task=sched.run(function()
  sched.signal('a signal', 'data')
  sched.sleep(1)
end)

Functions

get_time ()	Function used by the scheduler to get current time.
new_waitd (waitd_table)	Create a Wait Descriptor.
wait (waitd)	Wait for a signal.
sleep (timeout)	Sleeps the task for t time units.
new_task (f)	Create a task.
attach (taskd, taskd_child)	Attach a task to another.
set_as_attached (taskd)	Set a task as attached to the creator task.
run (task, ...)	Run a task.
sigrun (waitd, f, attached)	Create and run a task that listens for a signal.
sigrunonce (waitd, f, attached)	Create and run a task that listens for a signal, once.
set_pause (taskd, pause)	Pause a task.
kill (taskd)	Finishes a task.
signal (event, ...)	Emit a signal.
schedule_signal (event, ...)	Emit a signal lazily.
step ()	Runs a single step of the scheduler.
loop ()	Wait for the scheduler to finish.

Tables

EVENT_ANY	Event used for all events When included in a waitd, will match any event.
tasks	Tasks in scheduler.

Fields

running_task	Currently running task.
EVENT_DIE	Task died event.
EVENT_FINISH	Task finished event.
to_clean_up	Control memory collection.
idle	Idle function.

Data structures

waitd	Wait descriptor.
taskd	Task descriptor.

Functions

get_time ()

Function used by the scheduler to get current time. Replace with whatever your app uses. LuaSocket's gettime works just fine. Defaults to os.time.

new_waitd (waitd_table)

Create a Wait Descriptor. Creates waitd object in the scheduler. Notice that buffering waitds start buffering as soon they are created.

Parameters:

• waitd_table a table to convert into a wait descriptor.

Returns:

a wait descriptor object.

wait (waitd)

Wait for a signal. Pauses the task until (one of) the specified signal(s) is available. If there is a signal in the buffer, will return it immediately. Otherwise will block the task until signal arrival, or a timeout. If provided a table as parameter, will use new_waitd to convert it to a wait desciptor. If param is nil will yield to other tasks (as in cooperative multitasking) Can be invoked as waitd:wait().

Parameters:

• waitd a Wait Descriptor for the signal (see waitd)

Returns:

On event returns event, parameters. On timeout returns nil, 'timeout'

sleep (timeout)

Sleeps the task for t time units. Time computed according to @{get_time}.

Parameters:

• timeout time to sleep

new_task (f)

Create a task. The task is created in ready mode. The task will emit a sched.EVENT_FINISH, true, params... signal upon normal finalization, were params are the returns of f. If there is a error, the task will emit a sched.EVENT_DIE, false, err were err is the error message.

Parameters:

• f function for the task

Returns:

task in the scheduler (see taskd).

attach (taskd, taskd_child)

Attach a task to another. An attached task will be killed by the scheduler whenever the parent task is finished (returns, errors or is killed). Can be invoked as taskd:attach(taskd_child).

Parameters:

• taskd The parent task
• taskd_child The child (attached) task.

Returns:

the modified taskd.

set_as_attached (taskd)

Set a task as attached to the creator task. An attached task will be killed by the scheduler whenever the parent task (the task that created it) is finished (returns, errors or is killed). Can be invoked as taskd:set_as_attached().

Parameters:

• taskd The child (attached) task.

Returns:

the modified taskd.

run (task, ...)

Run a task. Can be provided either a taskd or a function, with optional parameters. If provided a taskd, will run it. If provided a function, will use new_task to create a task first. This call yields control to the new task immediatelly.

Parameters:

• task wither a taskd or function for the task.
• ... parameters passed to the task upon first run.

Returns:

a task in the scheduler (see taskd).

sigrun (waitd, f, attached)

Create and run a task that listens for a signal.

Parameters:

• waitd a Wait Descriptor for the signal (see waitd)
• f function to be called when the signal appears. The signal is passed to f as parameter.The signal will be provided as event, parameters, just as the result of a wait
• attached if true, the new task will run in attached mode

Returns:

task in the scheduler (see taskd).

sigrunonce (waitd, f, attached)

Create and run a task that listens for a signal, once.

Parameters:

• waitd a Wait Descriptor for the signal (see waitd)
• f function to be called when the signal appears. The signal is passed to f as parameter. The signal will be provided as event, parameters, just as the result of a wait
• attached if true, the new task will run in attached more

Returns:

task in the scheduler (see taskd).

set_pause (taskd, pause)

Pause a task. A paused task won't be scheduled for execution. If paused while waiting for a signal, won't respond to signals. Signals on unbuffered waitds will get lost. Task's buffered waitds will still buffer events. Can be invoked as taskd:set_pause(pause)

Parameters:

• taskd Task to pause (see taskd).
• pause mode, true to pause, false to unpause

Returns:

the modified taskd on success or nil, errormessage on failure.

kill (taskd)

Finishes a task. The killed task will emit a signal sched.EVENT_DIE, 'killed'. Can be invoked as taskd:kill().

Parameters:

• taskd task to terminate (see taskd).

signal (event, ...)

Emit a signal. Will give control immediatelly to tasks that are waiting on event, to regain it when they finish/block.

Parameters:

• event event of the signal. Can be of any type.
• ... further parameters to be sent with the signal.

schedule_signal (event, ...)

Emit a signal lazily. Like signal, except it does not yield control. Will schedule the event to be emitted after task yields by other means (it even can be delayed beyond that by the scheduler). Scheduled signals from multiple tasks will be emitted in order.

Parameters:

• event event of the signal. Can be of any type.
• ... further parameters to be sent with the signal.

step ()

Runs a single step of the scheduler.

Returns:

the idle time available until more activity is expected; this means it will be 0 if there are active tasks.

loop ()

Wait for the scheduler to finish. This call will block until there is no more task activity, i.e. there's no active task, and none of the waiting tasks has a timeout set.

Usage:

local sched = require 'lumen.sched'
sched.run(function()
   --start at least one task
end)
sched.loop()
--potentially free any resources before finishing here  

Tables

EVENT_ANY

Event used for all events When included in a waitd, will match any event.

tasks

Tasks in scheduler. Table holding taskd objects of the tasks in the scheduler.

Usage:

for taskd, _ in pairs (sched.tasks) do print(taskd) end

Fields

running_task

Currently running task. The task descriptor from current task.

EVENT_DIE

Task died event. This event will be emited when a task is either killed or finishes on error. The parameter is 'killed' if the task was killed, or the error message otherwise.

Usage:

--prints each time a task dies
sched.sigrun({sched.EVENT_DIE}, print)

EVENT_FINISH

Task finished event. This event will be emited when a task finishes normally. The parameters are the output of the task's function.

Usage:

--prints each time a task finishes
sched.sigrun({sched.EVENT_FINISH}, print)

to_clean_up

Control memory collection. number of new insertions in waiting[event] before triggering clean_up. Defaults to 1000

idle

Idle function. Function called by the scheduler when there is nothing else to do (e.g., all tasks are waiting for a signal). This function should idle up to t time units. Replace with whatever your app uses. LuaSocket's sleep works just fine. It is allowed to idle for less than t; the empty function will result in a busy wait. Defaults to execution of Linux's "sleep" command or the Windows ping hack.

• t time to idle

Data structures

waitd

Wait descriptor. Specifies a condition on which wait. Includes a signal description, a optional timeout specification and buffer configuration. A wait descriptor can be reused (for example, when waiting inside a loop) and shared amongst different tasks. If a wait descriptor changes while there is a task waiting, the behavior is unspecified. Notice that when sharing a wait descriptor between several tasks, the buffer is associated to the wait descriptor, and tasks will service buffered signals on first request basis.
Besides the following fields, provides methods for the sched functions that have a waitd as first parameter.

Fields:

• array The array part contains the events to wait. Can contain sched.EVENT_ANY to mark interest in any event. If nil, will only return on timeout.
• timeout optional, time to wait. nil or negative waits for ever.
• buff_mode Specifies how to behave when inserting in a full buffer. 'keep last' means replace with the new arrived signal. 'keep first' will skip the insertion in a full buffer. nil disables buffering

taskd

Task descriptor. Handler of a task. Besides the following fields, provides methods for the sched functions that have a taskd as first parameter.

Fields:

• status Status of the task, can be 'ready', 'paused' or 'dead'
• waitingfor If the the task is waiting for a signal, this is the Wait Descriptor (see waitd)
• waketime The time at which to task will be forced to wake-up (due to a timeout on a wait)
• created_by The task that started this one.
• attached Table containing attached tasks.
• co The coroutine of the task