FixTask Documentation

Back to summary

import "task/channel";

Channel class

Channel allows to send messages between different tasks. The channel can be either synchronous (the message is directly exchanged between the tasks at synchronization point) or asynchronous by using a queue.

When sending channels as a part of the message using the asynchronous variant of the channel the values are only weakly referenced to prevent memory leaks. An outside reference must be present (this is usually the case).

Functions

static function create(): Channel
static function create(size: Integer): Channel


Creates a new channel. When the size is non-zero an asynchronous channel is created with the given queue size.

function send(msg)
function send(msg, timeout: Integer): Boolean


Sends a message to the channel with an optional timeout (in milliseconds, negative value disables the timeout). Returns true if the message was delivered (when using timeout).

function receive(): Dynamic
function receive(timeout: Integer): Dynamic
function receive(timeout: Integer, timeout_value): Dynamic


Receives a message from the channel with an optional timeout (in milliseconds, negative value disables the timeout). If the message wasn't received within the provided time limit a special marker value is returned which you can check using the is_timeout function.

function get_sender(): Channel
function get_receiver(): Channel


Returns either the sender or receiver part of the channel to prevent inappropriate usage.

function get_shared_count(): Integer

Returns the reference count of the channel. Can be used to track liveness of the channel in other tasks in a similar fashion as shared arrays can be used.

function set_size(size: Integer)
function get_size(): Integer


Allows to adjust or get the queue size for asynchronous channels. The size can be changed only in the heap that created the channel, cloning to different heap will strip the ownership (even when the channel is cloned back to the original heap). Sender and receiver parts of the channel also can't be used to set the size.

function call(params: Dynamic[]): Dynamic

Uses the channel to do a synchronous function call (from the caller's point of view at least). The parameters (with appended internal return channel) are sent to the channel. It then waits for a message in the return channel to return. The returned value must be an array of one or two return values, or it can be null to not return anything.

function call(params: Dynamic[], func, data)

Asynchronous variant of call. Uses Dispatcher to call the provided callback once the result is available. The callback function receives the data as a first argument, the result as a second argument and the error as a third argument.

function handle(func)
function handle(func, error_func)
function handle(func, error_func, timeout: Integer)
function handle_sync(func)


Starts an endless loop that handles receiving of messages. The callback function receives the message as an argument. Optionally you can also pass an error callback with the message as a first argument and the error as a second argument. You can also pass a periodic timeout (in milliseconds), whenever it is reached the callback is called with a special timeout value that can be checked by using the is_timeout function. In the synchronous variant the return value of the callback is passed back unless Dispatcher::handle_async function is used. Use Dispatcher if you need more features.

Special values

static function is_timeout(value): Boolean

Returns true if the returned value is a special marker value denoting that a time limit has been reached.

static function is_error(value): Boolean

Returns true if the returned value is a special marker value denoting that an error has occurred.