Lumen

• Index

Contents

• Functions
• Tables
• Fields

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 selector

Module suporting asynchronous access to sockets and files.

Selector integrates Lumen with a select/poll-like mechanism.
Backends luasocket and nixio are supported.
The socket can be setup to react to data arrival by either calling a handler function, writing to a stream, or emiting signals.

Usage:

local selector = require 'lumen.selector'
selector.init({service='luasocket'})

Functions

init (conf)	Start the service.
new_tcp_server (locaddr, locport, pattern, handler)	Creates a TCP server socket.
new_tcp_client (address, port, locaddr, locport, pattern, handler)	Creates a TCP client socket.
new_udp (address, port, locaddr, locport, pattern, handler)	Creates a UDP socket.
new_fd (filename, flags, pattern, handler)	Opens a file.
grab_stdout (command, pattern, handler)	Grab the output of a command.
close (sktd)	Closes a socket/file.
send_sync (sktd, data)	Synchronous data send.
send ()	Alias for send_sync.
send_async (sktd, data)	Asynchronous data send.
getsockname (sktd)	Get the local address of a socket.
getpeername (sktd)	Get the remote address of a socket.

Tables

sktd	Socket/File descriptor.
conf	Configuration Table.

Fields

task	Task that emits signals.
ASYNC_SEND_BUFFER	Suggested max buffer size for asynchronous sending.

Functions

init (conf)

Start the service.

Parameters:

• conf the configuration table (see conf).

new_tcp_server (locaddr, locport, pattern, handler)

Creates a TCP server socket. Emits a sktd.events.accepted, client_sktd signal on new connections.

Parameters:

• locaddr Local IP address or '' (defaults to '')
• locport Local port (defaults to 0)
• pattern Any of nixio or luasocket patterns.
• handler Optional, a handler function or 'stream'. Will be used when creating new client sockets. See new_tcp_client. 'stream' mean a new stream will be created, and provided in the sktd object.

Returns:

a sktd object

new_tcp_client (address, port, locaddr, locport, pattern, handler)

Creates a TCP client socket. Can be set up to use a handler function, write to a stream, or emit signals (sktd.events.data, data signal on incommig data, and sktd.events.data, nil, err on errors).

Parameters:

• address Remote IP address.
• port Remote port ()
• locaddr Local IP address or '' (defaults to '')
• locport Local port (defaults to 0)
• pattern Any of nixio or luasocket patterns.
• handler Optional, either a handler function or a stream.
  The handler function must have a (sktd, data, err, part) signature. The handler must return true to keep the socket open, otherwised the socket will b e closed as soon as it returns (or errors).
  When a stream it will be used to push data as it arrives. On socket closing, the stream will be closed with the error message as provided by the socket.
  If the handler parameter is nil, the socket object will emit signals.

Returns:

a sktd object on success, nil, err on failure

new_udp (address, port, locaddr, locport, pattern, handler)

Creates a UDP socket. Can be set up to use a handler function, write to a stream, or emit signals (sktd.events.data, data signal on incommig data, and sktd.events.data, nil, err on errors).

Parameters:

• address Remote IP address.
• port Remote port ()
• locaddr Local IP address or '' (defaults to '')
• locport Local port (defaults to 0)
• pattern Any of nixio or luasocket patterns.
• handler Optional, either a handler function or a stream. The handler function must have a (sktd, data, err, part) signature. The handler must return true to keep the socket open, otherwised the socket will be closed as soon as it returns (or errors).
  When a stream it will be used to push data as it arrives. On socket closing, the stream will be closed with the error message as provided by the socket.
  If the handler parameter is nil, the socket object will emit signals.

Returns:

a sktd object

new_fd (filename, flags, pattern, handler)

Opens a file. Can be set up to use a handler function, write to a stream, or emit signals (sktd.events.data, data signal on incommig data, and sktd.events.data, nil, err on errors).

Parameters:

• filename
• flags ATM as specified for nixio.open()
• pattern Any of nixio or luasocket patterns.
• handler Optional, either a handler function or a stream. The handler function must have a (sktd, data, err, part) signature. The handler must return true to keep the socket open, otherwised the socket will be closed as soon as it returns (or errors).
  When a stream it will be used to push data as it arrives. On socket closing, the stream will be closed with the error message as provided by the socket.
  If the handler parameter is nil, the socket object will emit signals.

Returns:

a sktd object

grab_stdout (command, pattern, handler)

Grab the output of a command. Usefull for capturing the output of long running programs.
Can be set up to use a handler function, write to a stream, or emit signals (sktd.events.data, data signal on incommig data, and sktd.events.data, nil, err on errors).

Parameters:

• command command whose ouput capture
• pattern Any of nixio or luasocket patterns.
• handler Optional, either a handler function or a stream. The handler function must have a (sktd, data, err, part) signature. The handler must return true to keep the socket open, otherwised the socket will b e closed as soon as it returns (or errors).
  When a stream it will be used to push data as it arrives. On socket closing, the stream will be closed with the error message as provided by the socket.
  If the handler parameter is nil, the socket object will emit signals.

Returns:

a sktd object

close (sktd)

Closes a socket/file.

Parameters:

• sktd a sktd object

send_sync (sktd, data)

Synchronous data send. The task calling this function will block until all data is sent.

Parameters:

• sktd a sktd object
• data data to send

Returns:

true on success. nil, err, partial on failure

send ()

Alias for send_sync. can be reasigned to to send_async, if so preferred

send_async (sktd, data)

Asynchronous data send. This call return immediatelly. The data transmission will continue in background. Aditional calls will queue data. When all data queued for asynchronous transmission is sent, a sktd.events.async_finished, success signal is emitted.

Parameters:

• sktd a sktd object
• data data to send

getsockname (sktd)

Get the local address of a socket.

Parameters:

• sktd a sktd object

Returns:

ip, port

getpeername (sktd)

Get the remote address of a socket.

Parameters:

• sktd a sktd object

Returns:

ip, port

Tables

sktd

Socket/File descriptor. Provides OO-styled access to methods, such as sktd:send(data) and sktd:close()

Fields:

• task task that will emit signal related to this object
• stream If asigned a stream object, will write data into it (in addittion to signals)

conf

Configuration Table.

Fields:

• service backend to use: 'nixio' or 'luasocket' (default)

Fields

task

Task that emits signals.

ASYNC_SEND_BUFFER

Suggested max buffer size for asynchronous sending. Must be set before first call to async send. Defaults to 1mb.