The Lua Thread Library

Detailed Description

See Advanced Lua Bindings, section Calling Lua Code Asynchronously From C Code for how to use this class.

Collaboration diagram for The Lua Thread Library:

Classes
struct	LThreadMgr
	Run native jobs and protected Lua callbacks on BAS worker threads. More...
struct	ThreadJob
	An owned unit of work created by ThreadJob_create or ThreadJob_lcreate. More...

Macros
#define	LThreadMgr_canRun(o)   ! DoubleList_isEmpty(&(o)->idleThreadList)
	This function returns true if at least one thread is currently idle and there is no need to queue the job when calling LThreadMgr_run. More...
#define	LThreadMgr_enableHttpPool(o, server)    HttpServer_setThreadPoolIntf(server, (HttpCmdThreadPoolIntf*)o)
	LThreadMgr can be used as a Thread Pool and is often utilized in real-time operating system (RTOS) devices with limited resources as a substitute for HttpCmdThreadPool. More...

Typedefs
typedef void(*	ThreadJob_Run) (struct ThreadJob *tj, struct LThreadMgr *mgr)
	Generic ThreadJob callback. More...
typedef void(*	ThreadJob_LRun) (struct ThreadJob *tj, int msgh, struct LThreadMgr *mgr)
	ThreadJob callback designed for calling Lua code using lua_pcall. More...
typedef struct LThreadMgr	LThreadMgr
	Run native jobs and protected Lua callbacks on BAS worker threads. More...
typedef struct ThreadJob	ThreadJob
	An owned unit of work created by ThreadJob_create or ThreadJob_lcreate. More...

Functions
BA_API void	LThreadMgr_destructor (LThreadMgr *o)
	This function terminates the Thread Pool and waits for all threads to stop before returning. More...
BA_API void	LThreadMgr_constructor (LThreadMgr *o, HttpServer *server, ThreadPriority priority, int stackSize, int threads, lua_State *L, int allowCreate)
	Initialize the thread pool and install ba.thread. More...
BA_API ThreadJob *	ThreadJob_create (size_t size, ThreadJob_Run run)
	Create a generic thread job. More...
BA_API ThreadJob *	ThreadJob_lcreate (size_t size, ThreadJob_LRun lrun)
	Create a thread job designed to execute Lua code. More...
BA_API int	LThreadMgr_run (LThreadMgr *o, ThreadJob *tj)
	This function sends a thread job to an available idle thread, or queues the job if no threads are currently available. More...

Macro Definition Documentation

LThreadMgr_canRun

#define LThreadMgr_canRun

(

o

)

! DoubleList_isEmpty(&(o)->idleThreadList)

This function returns true if at least one thread is currently idle and there is no need to queue the job when calling LThreadMgr_run.

Parameters

o	Required initialized manager; its server mutex must be held.

Returns

Nonzero if a worker is idle, zero otherwise. This is not a job result.

LThreadMgr_enableHttpPool

#define LThreadMgr_enableHttpPool	(		o,
			server
	)		HttpServer_setThreadPoolIntf(server, (HttpCmdThreadPoolIntf*)o)

LThreadMgr can be used as a Thread Pool and is often utilized in real-time operating system (RTOS) devices with limited resources as a substitute for HttpCmdThreadPool.

Parameters

o	the LThreadMgr instance
server	the HttpServer instance

Typedef Documentation

LThreadMgr

typedef struct LThreadMgr LThreadMgr

Run native jobs and protected Lua callbacks on BAS worker threads.

The host creates its global manager after HttpServer and the Lua state; applications can create dynamic managers with ba.thread.create. The manager borrows the server and Lua state. Keep both alive until LThreadMgr_destructor returns, and stop submitting work before teardown.

Submit job-owned input through ThreadJob and LThreadMgr_run. Lua callbacks execute with the server mutex held; arbitrary OS threads must not call Lua directly. See ThreadJob_LRun and Advanced Lua Bindings for the callback pattern, and LThreadMgr_constructor for worker and stack settings.

ThreadJob

typedef struct ThreadJob ThreadJob

An owned unit of work created by ThreadJob_create or ThreadJob_lcreate.

Copy callback input into job-owned storage before submission. After LThreadMgr_run queues the job, the manager owns it regardless of the function's worker-availability return value; do not free or requeue it from the callback. Lt is borrowed only during that callback. Pending jobs can be discarded during manager teardown, so stop event producers before destroying the manager. See Advanced Lua Bindings.

ThreadJob_LRun

typedef void(* ThreadJob_LRun) (struct ThreadJob *tj, int msgh, struct LThreadMgr *mgr)

ThreadJob callback designed for calling Lua code using lua_pcall.

The server mutex is held. Use tj->Lt and pass msgh to lua_pcall. The manager frees the job and clears the thread stack after return. Do not free/requeue the job, retain tj->Lt, or allow an unprotected Lua error to escape.

Parameters

tj	the job passed into function LThreadMgr_run
msgh	the index position to the BAS error handler function
mgr	the manager associated with the global or dynamically created instance via ba.thread.create

ThreadJob_Run

typedef void(* ThreadJob_Run) (struct ThreadJob *tj, struct LThreadMgr *mgr)

Generic ThreadJob callback.

The server mutex is held. The manager frees the job after return and clears its Lua stack. Do not free or requeue the job or retain its thread state. Release the mutex for blocking external work and reacquire it before return.

Parameters

tj	the job passed into function LThreadMgr_run
mgr	the manager associated with the global or dynamically created instance via ba.thread.create

Function Documentation

LThreadMgr_constructor()

BA_API void LThreadMgr_constructor	(	LThreadMgr *	o,
		HttpServer *	server,
		ThreadPriority	priority,
		int	stackSize,
		int	threads,
		lua_State *	L,
		int	allowCreate
	)

Initialize the thread pool and install ba.thread.

Call with the server mutex held. The server and Lua state are borrowed and must outlive the manager. Lua allocation errors and native thread-creation failures use the underlying Lua/platform error handling, not a return code.

Parameters

o	The LThreadMgr instance to initialize.
server	The HttpServer instance that owns the pool.
priority	typically set to ThreadPrioNormal
stackSize	typically set to BA_THREAD_STACK_SIZE
threads	Positive initial worker count; zero provides no workers.
L	the Lua state returned by balua_create
allowCreate	set to TRUE to enable the two APIs ba.thread.create and ba.thread.configure

LThreadMgr_destructor()

BA_API void LThreadMgr_destructor

(

LThreadMgr *

o

)

This function terminates the Thread Pool and waits for all threads to stop before returning.

Pending jobs may be discarded without callbacks.

Parameters

o	Required initialized manager. Stop submitting jobs first. Its server mutex must be held; it is released and reacquired while waiting. Keep the server and Lua VM alive until this returns, and do not call from its worker.

LThreadMgr_run()

BA_API int LThreadMgr_run	(	LThreadMgr *	o,
		ThreadJob *	tj
	)

This function sends a thread job to an available idle thread, or queues the job if no threads are currently available.

Before calling this method from outside of the server environment, you must have ownership of the SoDisp ThreadMutex.

Parameters

o	Required running manager with at least one worker.
tj	Required allocated job, not already queued. Ownership transfers.

Returns

TRUE if an idle worker was signalled, FALSE if only queued. Both results mean the job was accepted; neither reports callback completion.

ThreadJob_create()

BA_API ThreadJob * ThreadJob_create	(	size_t	size,
		ThreadJob_Run	run
	)

Create a generic thread job.

Parameters

size	at least sizeof(ThreadJob)
run	Required callback. Your callback function will execute in the context of a thread within the Thread Manager

Returns

The allocated job, or NULL if memory allocation fails. Do not queue a NULL job. Additional payload storage is uninitialized. Before queuing, the caller owns the allocation and may release it with baFree. Queuing transfers ownership to the manager, which frees it after the callback.

ThreadJob_lcreate()

BA_API ThreadJob * ThreadJob_lcreate	(	size_t	size,
		ThreadJob_LRun	lrun
	)

Create a thread job designed to execute Lua code.

Parameters

size	at least sizeof(ThreadJob)
lrun	Required callback. Your callback function will execute in the context of a thread within the Thread Manager

Returns

The allocated job, or NULL if memory allocation fails. Do not queue a NULL job. Additional payload storage is uninitialized. Before queuing, the caller owns the allocation and may release it with baFree. Queuing transfers ownership to the manager, which frees it after the callback.