Freestanding C11 interface for the LibJuno Thread module. More...

#include <stdint.h>
#include <stdbool.h>
#include "juno/status.h"
#include "juno/module.h"
#include "juno/types.h"

Include dependency graph for thread_api.h:

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

Go to the source code of this file.

Data Structures
struct	JUNO_THREAD_API_TAG
	Thread module vtable (API struct). More...

Typedefs
typedef struct JUNO_THREAD_ROOT_TAG	JUNO_THREAD_ROOT_T
	Forward declaration of the Thread module root struct.

typedef struct JUNO_THREAD_API_TAG	JUNO_THREAD_API_T
	Forward declaration of the Thread vtable struct.

typedef struct JUNO_THREAD_LINUX_TAG	JUNO_THREAD_LINUX_T
	Forward declaration of the Linux/POSIX derivation struct.

typedef union JUNO_THREAD_TAG	JUNO_THREAD_T
	Forward declaration of the Thread module union. The full union body is defined in `juno/thread_linux.h` after the platform derivation type is complete.

Functions
struct JUNO_THREAD_ROOT_TAG	JUNO_MODULE_ROOT (JUNO_THREAD_API_T, volatile bool bStop;)
	Thread module root struct (freestanding, cross-platform).

JUNO_STATUS_T	JunoThread_Init (JUNO_THREAD_ROOT_T ptRoot, const JUNO_THREAD_API_T ptApi, JUNO_FAILURE_HANDLER_T pfcnFailureHandler, void *pvFailureUserData)
	Initialise a Thread module root with a concrete vtable and failure handler.

Detailed Description

Freestanding C11 interface for the LibJuno Thread module.

Provides a vtable-based abstraction for managing a single OS thread. This header is freestanding-compatible: it does not include any POSIX or OS-specific headers (pthread.h, unistd.h, etc.) and may be compiled with -nostdlib -ffreestanding.

The module supports a cooperative shutdown model. The thread entry function periodically reads ptRoot->bStop; when it is true the entry function exits its loop and returns. The caller then calls Join to reap the OS thread.

Platform-specific details (OS handle, thread creation) are confined to thread_linux.h and the corresponding implementation translation unit. The union JUNO_THREAD_T provides storage large enough for any derivation; callers allocate it and pass &tThread.tRoot to all API functions.

Typical usage:

#include "juno/thread_linux.h"   // platform header provides JunoThread_LinuxInit
 
static JUNO_THREAD_T tThread = {0};
 
// Platform init spawns the thread immediately (RAII)
JunoThread_LinuxInit(&tThread, MyEntryFunction, &tThread.tRoot,
                     FailureHandler, NULL);
 
// Cooperative shutdown
tThread.tRoot.ptApi->Stop(&tThread.tRoot);
tThread.tRoot.ptApi->Join(&tThread.tRoot);
tThread.tRoot.ptApi->Free(&tThread.tRoot);

Typedef Documentation

◆ JUNO_THREAD_API_T

typedef struct JUNO_THREAD_API_TAG JUNO_THREAD_API_T

Forward declaration of the Thread vtable struct.

◆ JUNO_THREAD_LINUX_T

typedef struct JUNO_THREAD_LINUX_TAG JUNO_THREAD_LINUX_T

Forward declaration of the Linux/POSIX derivation struct.

◆ JUNO_THREAD_ROOT_T

typedef struct JUNO_THREAD_ROOT_TAG JUNO_THREAD_ROOT_T

Forward declaration of the Thread module root struct.

◆ JUNO_THREAD_T

typedef union JUNO_THREAD_TAG JUNO_THREAD_T

Forward declaration of the Thread module union. The full union body is defined in juno/thread_linux.h after the platform derivation type is complete.

Function Documentation

◆ JUNO_MODULE_ROOT()

struct JUNO_THREAD_ROOT_TAG JUNO_MODULE_ROOT	(	JUNO_THREAD_API_T	,
		volatile bool bStop;
	)

Thread module root struct (freestanding, cross-platform).

The root struct is the shared, freestanding portion of the Thread module. It carries the vtable pointer, the optional failure handler and its user data (all injected by JUNO_MODULE_ROOT), and the single cross-platform state field needed by thread entry functions.

The OS thread handle (pthread_t or equivalent) is NOT stored here. It lives in the platform derivation (e.g., JUNO_THREAD_LINUX_T) so that this header remains compilable without any POSIX headers.

The bStop field has no leading underscore because it is part of the public cooperative-shutdown protocol: the thread entry function reads ptRoot->bStop directly to decide when to exit its loop.

◆ JunoThread_Init()

JUNO_STATUS_T JunoThread_Init	(	JUNO_THREAD_ROOT_T *	ptRoot,
		const JUNO_THREAD_API_T *	ptApi,
		JUNO_FAILURE_HANDLER_T	pfcnFailureHandler,
		void *	pvFailureUserData
	)

Initialise a Thread module root with a concrete vtable and failure handler.

Wires ptApi into ptRoot->ptApi, stores the failure handler and its user data, and clears the cooperative-shutdown flag (bStop = false). Must be called before any vtable dispatch.

Callers that use the Linux/POSIX implementation should call JunoThread_LinuxInit instead; it calls this function internally and also spawns the OS thread.

Parameters

ptRoot	Caller-owned root storage. Must not be NULL.
ptApi	Vtable (e.g., `&g_junoThreadLinuxApi`). Must not 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 ptRoot or ptApi is NULL.

Initialise a Thread module root with a concrete vtable and failure handler.

Wires the vtable pointer into the root, clears the cooperative stop flag, and stores the optional failure handler and its associated user-data pointer. This function must be called before any vtable dispatch function (Stop, Join, Free).

The OS thread handle is not initialised here; it is stored in the platform-specific derivation and set by JunoThread_LinuxInit after a successful pthread_create call.