This page contains a quick reference for the Leda library API:

Leda Main API

leda.stage({...})

This function creates a stage object reference and its passed

Parameters:

	'handler' type: function(...) (required field)
		This is the function that will be used as the 
		event handler for the created stage.
		It will receive the unpacked event at every execution as its parameters.
		
	'init' type: function() (optional field)
		If defined, this function is called after the creation of a instance
		of the created stage.
			
	'bind' type: function({connectors}) (optional field)
		If defined, this function is called before the execution of
		the stage graph containing this stage. 
		It will receive the output connectors table defined on the running graph as its parameter.
	
	'serial' or 'stateful' type: boolean (optional field)
		if 'false' or 'nil' the stage wont have persistent state. Multiple
		        parallel instances os this stages can be created by the runtime.
		else the stage will have a persistent state, but all events are
			whithin this stage will be serialized.
					
	'name' type: string (optional field)
		Optional 'name' of the stage used in the tostring() metamethod

Stage object methods:

stage1:connect(key, stage2, type)

Create a connector between two stages

	         - key: Index for the connector on the output ports (default is the value '1')
	         - stage2: Target stage
	         - type: Connector type, can be "local" or "decoupled" (default)

stage:send(...)

Put event into the stage's event queue

	         - ... : Event data

leda.cluster(stage1,stage2,...)

Create a cluster object containing the stages passed as function parameters. Clusters can be manipulated with the following arithmetic operators:

• cluster1 + cluster2 = Union between two clusters
• cluster1 - cluster2 = Difference between two clusters
• cluster1 * cluster2 = Intersection between two clusters

leda.graph({...})

This function creates a new stage graph from an array of connectors received as parameter.

Optional fields:

	'start' type: stage
		Define a starting stage for this graph. Used by the send method of the graph.

	'name' type: string
		Optional 'name' of the graph used in the tostring() metamethod

Graph object methods:

graph:run({...})

Starts the execution of a graph.

	     Parameter: a table with the following optional fields:
	         - controller: A controller reference to be used by the runtime.
	         - maxpar: Maximum number of parallel instances of stages in this graph.
	         - port: TCP port to be used in the inter-process communication mecanism.

Example:

... --graph definition
require "leda.controller.fixed_thread_pool" --> load the fixed thread pool controller
graph:run{controller=leda.controller.fixed_thread_pool.get(10)} --> get the controller with 10 fixed threads

graph:part(cluster1,cluster2,...,clusterN)

Creates a partition on the graph. It expects a ordered list of clusters with stages belonging to the graph as a parameter. Each of stage of the graph must be inside of exactly one defined cluster for a partition to be valid. - This function raises an error in the case of an invalid cluster configuration

graph:map('host1:port','host2:port',...,'hostN:port')

Map each previously defined cluster to a exclusive process. Each remote process must be started before the execution of the graph.

graph:all()

Returns a cluster with all stages defined on the graph.

Examples:

    graph:part(graph:all()) --> Partition the graph with a single cluster with all stages of the graph
    graph:map("localhost") --> Map the cluster to the local process

    graph:part(graph:all()-stage1,leda.cluster(stage1)) --> Partition the graph with two clusters
    graph:map("host1.localdomain.com:9999","host2.localdomain.com:9999") --> Map both clusters

leda.start({...})

Starts a new Leda process and waits for the execution of a graph with a cluster mapped to this process.

	     Parameter: a table with the following optional fields:
	         - controller: A controller reference to be used by the runtime.
	         - maxpar: Maximum number of parallel instances of stages in this graph.
	         - port: TCP port to be used in the inter-process communication mecanism.

Leda Stage API

The following functions can be called by event handlers and are only available inside active instances of its stage.

leda.send(output_key, ...)

Send an event to an output port. Returns true if the event was successfully delivered to an event queue of a stage, or nil and an error message if the event cannot be delivered.

leda.sleep(time)

Causes the current running instance to sleep for a period of time (in seconds).

leda.quit(exit_code)

Terminate the execution of the current process with exit_code.

leda.gettime()

Returns the current time.

leda.nice()

Release the current thread for other instances that are ready to execute (equivalent of leda.sleep(0))