thread_linux.h File Reference

Linux/POSIX-specific concrete derivation of the LibJuno Thread module. More...

#include "juno/thread_api.h"
#include <pthread.h>

Include dependency graph for thread_linux.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct JUNO_THREAD_LINUX_TAG	JUNO_THREAD_LINUX_T

Functions
struct JUNO_THREAD_LINUX_TAG	JUNO_MODULE_DERIVE (JUNO_THREAD_ROOT_T, pthread_t _tHandle;)
	Linux/POSIX concrete derivation of the Thread module.
union JUNO_THREAD_TAG	JUNO_MODULE (JUNO_THREAD_API_T, JUNO_THREAD_ROOT_T, JUNO_THREAD_LINUX_T tLinux;)
	Type-safe polymorphic handle for a Thread module instance.
JUNO_STATUS_T	JunoThread_LinuxInit (JUNO_THREAD_T *ptThread, void *(*pfcnEntry)(void *), void *pvArg, JUNO_FAILURE_HANDLER_T pfcnFailureHandler, void *pvFailureUserData)
	Initialise a Thread module instance and immediately spawn the OS thread.

Detailed Description

Linux/POSIX-specific concrete derivation of the LibJuno Thread module.

This header provides the Linux/pthreads concrete derivation of the Thread module defined by juno/thread_api.h. It is the ONLY Thread-module header that may include pthread.h; all other translation units that require only the abstract interface should include juno/thread_api.h.

The derivation struct JUNO_THREAD_LINUX_T extends the freestanding root (JUNO_THREAD_ROOT_T) by adding the native OS thread handle (pthread_t). Because pthread_t cannot be represented as a freestanding type it is confined here, away from the generic interface.

JunoThread_LinuxInit follows a RAII model: it wires the vtable, stores the failure handler, and immediately spawns the OS thread via pthread_create. No separate Create step is required.

Typical usage:

#include "juno/thread_linux.h"
 
static JUNO_THREAD_T tThread = {0};
 
// Initialise and spawn the thread in one call
JunoThread_LinuxInit(&tThread, WorkerEntry, &tThread.tRoot,
                     FailureHandler, NULL);
 
// Cooperative shutdown sequence
tThread.tRoot.ptApi->Stop(&tThread.tRoot);
tThread.tRoot.ptApi->Join(&tThread.tRoot);
tThread.tRoot.ptApi->Free(&tThread.tRoot);

Typedef Documentation

JUNO_THREAD_LINUX_T

typedef struct JUNO_THREAD_LINUX_TAG JUNO_THREAD_LINUX_T

Function Documentation

JUNO_MODULE()

union JUNO_THREAD_TAG JUNO_MODULE	(	JUNO_THREAD_API_T	,
		JUNO_THREAD_ROOT_T	,
		JUNO_THREAD_LINUX_T tLinux;
	)

Type-safe polymorphic handle for a Thread module instance.

Callers allocate this union (stack or static) and pass &tThread.tRoot to JunoThread_Init and to all subsequent vtable dispatches. The union is defined here — in the platform header — because it requires the complete type JUNO_THREAD_LINUX_T, which in turn requires pthread.h.

The union body satisfies the forward declaration of JUNO_THREAD_T made in juno/thread_api.h.

static JUNO_THREAD_T tThread = {0};
JunoThread_LinuxInit(&tThread, WorkerEntry, &tThread.tRoot,
                     FailureHandler, NULL);
tThread.tRoot.ptApi->Stop(&tThread.tRoot);
tThread.tRoot.ptApi->Join(&tThread.tRoot);
tThread.tRoot.ptApi->Free(&tThread.tRoot);

JUNO_MODULE_DERIVE()

struct JUNO_THREAD_LINUX_TAG JUNO_MODULE_DERIVE	(	JUNO_THREAD_ROOT_T	,
		pthread_t _tHandle;
	)

Linux/POSIX concrete derivation of the Thread module.

Embeds JUNO_THREAD_ROOT_T as its first member (tRoot, aliased by JUNO_MODULE_SUPER), enabling a safe pointer up-cast from any vtable callback that receives a JUNO_THREAD_ROOT_T * parameter.

The _tHandle field stores the native pthread_t returned by pthread_create. It is a private implementation detail; callers must not read or write it directly.

JunoThread_LinuxInit()

JUNO_STATUS_T JunoThread_LinuxInit	(	JUNO_THREAD_T *	ptThread,
		void *(*)(void *)	pfcnEntry,
		void *	pvArg,
		JUNO_FAILURE_HANDLER_T	pfcnFailureHandler,
		void *	pvFailureUserData
	)

Initialise a Thread module instance and immediately spawn the OS thread.

This function combines generic module initialisation with platform thread creation in a single RAII call:

1. Guards ptThread (returns JUNO_STATUS_NULLPTR_ERROR if NULL).
2. Guards pfcnEntry (returns JUNO_STATUS_NULLPTR_ERROR if NULL).
3. Calls JunoThread_Init internally, wiring g_junoThreadLinuxApi as the vtable — callers do NOT pass a ptApi parameter.
4. Clears bStop to false.
5. Calls pthread_create with pfcnEntry and pvArg; on failure returns JUNO_STATUS_ERR.
6. Stores the resulting pthread_t in ptThread->tLinux._tHandle.

Parameters

ptThread	Caller-owned JUNO_THREAD_T union. Must not be NULL.
pfcnEntry	Thread entry function (POSIX signature). Must not be NULL. Typically reads bStop from its argument to detect cooperative shutdown.
pvArg	Argument forwarded verbatim to pfcnEntry; may be NULL. Callers typically pass &ptThread->tRoot so the entry function can read bStop.
pfcnFailureHandler	Diagnostic callback invoked before any error return; may be NULL.
pvFailureUserData	Opaque pointer threaded to pfcnFailureHandler; may be NULL.

Returns

JUNO_STATUS_SUCCESS on success; JUNO_STATUS_NULLPTR_ERROR if a required pointer is NULL; JUNO_STATUS_ERR if pthread_create fails.

1. Guards ptThread and pfcnEntry (returns JUNO_STATUS_NULLPTR_ERROR if either is NULL).
2. Calls JunoThread_Init to wire s_tJunoThreadLinuxApi, clear bStop, and store the failure handler.
3. Zeroes ptThread->tLinux._tHandle.
4. Calls pthread_create; on failure returns JUNO_STATUS_ERR.
5. Stores the resulting pthread_t in ptThread->tLinux._tHandle.

Parameters

ptThread	Caller-owned JUNO_THREAD_T union. Must not be NULL.
pfcnEntry	Thread entry function. Must not be NULL.
pvArg	Argument forwarded verbatim to pfcnEntry; may be NULL.
pfcnFailureHandler	Diagnostic callback invoked before any error return; may be NULL.
pvFailureUserData	Opaque pointer threaded to pfcnFailureHandler; may be NULL.

Returns

JUNO_STATUS_SUCCESS on success.

JUNO_STATUS_NULLPTR_ERROR if a required pointer is NULL.

JUNO_STATUS_ERR if pthread_create() fails.