ljuv (halted)

Shared flag

ljuv.new_shared_flag(value [, final_value])

Create a shared flag.

• value: integer (C int)
• final_value: same as value, but set at finalization

shared_flag:set(value)

Set the shared flag's value.

• value: integer (C int)

shared_flag:get()

Returns the shared flag's value.

Channel

ljuv.new_channel()

Create a channel.

channel:push(...)

Push a message.

• ...: payload arguments (encoded by String Buffers)

channel:pull()

Pull a message (blocking).

Returns payload arguments.

channel:try_pull()

Pull a message (non-blocking).

Returns a boolean status, true followed by the payload arguments if a message has been pulled, or false otherwise.

channel:count()

Count the number of pending messages.

Object transfer

ljuv.export(object [, soft])

Export an object to be passed to another thread.

Exportables:

• channel:
• shared flag:
• async handle: imported as a function which safely calls async:send

Warning: The returned payload must be imported exactly once to prevent memory leak and invalid memory accesses.

Parameters:

• object: object to export
• soft: truthy to not throw errors on invalid object (returns nothing)

Returns a payload encodable by String Buffers.

ljuv.import(payload [, soft])

Import an object payload.

• payload:
• soft: truthy to not throw errors on invalid payload (returns nothing)

Returns imported object.

Thread abstraction

loop:thread(entry, callback, ...)

Create a new system-thread and run a Lua function asynchronously.

The created Lua state inherits from the current values of package.path and package.cpath.

Warning: The loop will not synchronously wait on running threads if garbage collected; the application should asynchronously wait on the callback.

• entry: thread entry function, a Lua function or a string of Lua code/bytecode

  Note: It uses string.dump to convert the Lua function to bytecode. Nothing will be done about the function's upvalues.

• callback(ok, ...): Called when terminated; common soft error handling interface: returns ok status followed by an error message or the function return values (encoded by String Buffers).

• ...: arguments passed to the function, must be encodable by String Buffers

Note: The Lua VM of the thread is closed from the system thread of the loop.

Threadpool abstraction

This abstraction, built on the previous one, implements a way to distribute operations among multiple threads from the "main" thread. Each thread instantiates the interface to process the work it is given.

I.e. main thread -> split workload -> worker threads -> gather results -> main thread.

loop:threadpool(thread_count, interface_loader, ...)

Create a system-thread pool.

• thread_count: number of threads in the pool
• interface_loader: Lua function or code, plain or bytecode, which returns a map of functions (called from worker threads)
• ...: interface loader arguments

Warning: Because each thread will execute the same interface loader, be careful to not use exported shared objects as arguments.

If the interface has an __exit function, it will be called before the end of the thread, after the exit of the work loop. It can be used to clean up interface resources.

threadpool:call(op, callback, ...)

Call an operation on the thread pool interface.

The callback can be a coroutine (will call coroutine.resume with the same parameters).

• op: key to an operation of the interface
• callback(ok, ...): Called on operation return, common soft error handling interface: returns ok status followed by an error message or the function return values (encoded by String Buffers).
• ...: call arguments (encoded by String Buffers)

threadpool.interface[op](...)

Same as threadpool:call, but synchronously from the current coroutine. Errors are propagated.

Example:

pool.interface.test(42)

threadpool:close([callback])

Close the thread pool (send exit signal to all threads). Idempotent.

• Without a callback (sync): wait from the current coroutine
• With a callback (async): called when closed

Note: This method should be called when all work is done, because only the application knows the context of the work it yet has to give to the pool.

threadpool.tasks

Table/map of id => callback.

Can be used to check if the pool is busy (waiting on tasks to return).