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
	The global instance created by C code or a dynamic instance created by ba.thread.create More...
struct	ThreadJob
	A thread job 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 pcall. More...
typedef struct LThreadMgr	LThreadMgr
	The global instance created by C code or a dynamic instance created by ba.thread.create
typedef struct ThreadJob	ThreadJob
	A thread job created by ThreadJob_create or ThreadJob_lcreate.

Functions
BA_API void	LThreadMgr_destructor (LThreadMgr *o)
	This function terminates the Thread Pool and waits for all threads to become idle before returning.
BA_API void	LThreadMgr_constructor (LThreadMgr *o, HttpServer *server, ThreadPriority priority, int stackSize, int threads, lua_State *L, int allowCreate)
	Initialize the Thread Pool. 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	the LThreadMgr instance

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

ThreadJob_LRun

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

ThreadJob callback designed for calling Lua code using pcall.

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.

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.

Parameters

o
server
priority	typically set to ThreadPrioNormal
stackSize	typically set to BA_STACKSZ
threads	Specify the initial number of threads to create
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_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.

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	Your callback function will execute in the context of a thread within the Thread Manager

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	Your callback function will execute in the context of a thread within the Thread Manager