(/usr/bin/git)

Header defining the central Task Data Structure and related types/functions. More...

#include <pthread.h>
#include <stddef.h>
#include "task.h"

Include dependency graph for taskdb.h:

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

Data Structures
struct	crinitTaskDB

Macros
#define	CRINIT_MONITOR_DEP_NAME "@crinitmon"
	Special dependency name to depend on monitor events (not yet impl.).

#define	CRINIT_PROVIDE_DEP_NAME "@provided"
	Special dependency name to depend on provided system features.

#define	CRINIT_TASKDB_INITIAL_SIZE 256
	Default initial size of taskSet and inclSet within an crinitTaskDB_t.

#define	crinitTaskDbForEach(taskDb, task) for ((task) = (taskDb)->taskSet; (task) != (taskDb)->taskSet + (taskDb)->taskSetItems; (task)++)

#define	crinitTaskDBUpdate(ctx, t) crinitTaskDBInsert(ctx, t, true)

#define	crinitTaskDBInit(ctx, spawnFunc) crinitTaskDBInitWithSize(ctx, spawnFunc, CRINIT_TASKDB_INITIAL_SIZE);

Typedefs
typedef enum crinitDispatchThreadMode	crinitDispatchThreadMode_t

typedef struct crinitTaskDB	crinitTaskDB_t

Enumerations
enum	crinitDispatchThreadMode { CRINIT_DISPATCH_THREAD_MODE_START , CRINIT_DISPATCH_THREAD_MODE_STOP }

Functions
int	crinitTaskDBInsert (crinitTaskDB_t ctx, const crinitTask_t t, bool overwrite)

int	crinitTaskDBFulfillDep (crinitTaskDB_t ctx, const crinitTaskDep_t dep, crinitTask_t *target)

int	crinitTaskDBProvideFeature (crinitTaskDB_t ctx, const crinitTask_t provider, crinitTaskState_t newState)

int	crinitTaskDBProvideFeatureByTaskName (crinitTaskDB_t ctx, const char taskName, crinitTaskState_t newState)

int	crinitTaskDBAddDepToTask (crinitTaskDB_t ctx, const crinitTaskDep_t dep, const char *taskName)

int	crinitTaskDBRemoveDepFromTask (crinitTaskDB_t ctx, const crinitTaskDep_t dep, const char *taskName)

int	crinitTaskDBGetTaskByName (crinitTaskDB_t ctx, crinitTask_t task, const char taskName)

int	crinitTaskRearmTrigger (crinitTaskDB_t ctx, const char taskName)

int	crinitTaskDBSetTaskState (crinitTaskDB_t ctx, crinitTaskState_t s, const char taskName)

int	crinitTaskDBGetTaskState (crinitTaskDB_t ctx, crinitTaskState_t s, const char *taskName)

int	crinitTaskDBSetTaskPID (crinitTaskDB_t ctx, pid_t pid, const char taskName)

int	crinitTaskDBGetTaskPID (crinitTaskDB_t ctx, pid_t pid, const char *taskName)

int	crinitTaskDBGetTaskStateAndPID (crinitTaskDB_t ctx, crinitTaskState_t s, pid_t pid, const char taskName)

int	crinitTaskDBSetTaskRespawnInhibit (crinitTaskDB_t ctx, bool inhibit, const char taskName)

crinitTask_t *	crinitTaskDBBorrowTask (crinitTaskDB_t ctx, const char taskName)

int	crinitTaskDBRemit (crinitTaskDB_t *ctx)

int	crinitTaskDBSpawnReady (crinitTaskDB_t *ctx, crinitDispatchThreadMode_t mode)

int	crinitTaskDBSetSpawnInhibit (crinitTaskDB_t *ctx, bool inh)

int	crinitTaskDBInitWithSize (crinitTaskDB_t ctx, int(spawnFunc)(crinitTaskDB_t ctx, const crinitTask_t , crinitDispatchThreadMode_t mode), size_t initialSize)

int	crinitTaskDBDestroy (crinitTaskDB_t *ctx)

int	crinitTaskDBExportTaskNamesToArray (crinitTaskDB_t ctx, char tasks[], size_t numTasks)

Detailed Description

Header defining the central Task Data Structure and related types/functions.

Macro Definition Documentation

◆ CRINIT_MONITOR_DEP_NAME

#define CRINIT_MONITOR_DEP_NAME "@crinitmon"

Special dependency name to depend on monitor events (not yet impl.).

◆ CRINIT_PROVIDE_DEP_NAME

#define CRINIT_PROVIDE_DEP_NAME "@provided"

Special dependency name to depend on provided system features.

◆ CRINIT_TASKDB_INITIAL_SIZE

#define CRINIT_TASKDB_INITIAL_SIZE 256

Default initial size of taskSet and inclSet within an crinitTaskDB_t.

◆ crinitTaskDbForEach

#define crinitTaskDbForEach	(	taskDb,
		task
	)	for ((task) = (taskDb)->taskSet; (task) != (taskDb)->taskSet + (taskDb)->taskSetItems; (task)++)

Iterate over all tasks in a task database

Parameters

taskDb	Pointer to a task database to traverse.
task	Pointer to a single task entry.

◆ crinitTaskDBInit

#define crinitTaskDBInit	(	ctx,
		spawnFunc
	)	crinitTaskDBInitWithSize(ctx, spawnFunc, CRINIT_TASKDB_INITIAL_SIZE);

Initialize the internals of an crinitTaskDB_t with the default initial size of CRINIT_TASKDB_INITIAL_SIZE.

See crinitTaskDBInitWithSize().

◆ crinitTaskDBUpdate

#define crinitTaskDBUpdate	(	ctx,
		t
	)	crinitTaskDBInsert(ctx, t, true)

Insert a task into a task database, overwriting a task with the same name if it exists.

For explanation see crinitTaskDBInsert() with parameter overwrite set to true.

Typedef Documentation

◆ crinitDispatchThreadMode_t

typedef enum crinitDispatchThreadMode crinitDispatchThreadMode_t

Type to describe wheter the spawn thread launches start or stop commands

◆ crinitTaskDB_t

typedef struct crinitTaskDB crinitTaskDB_t

Type to store a task database.

Enumeration Type Documentation

◆ crinitDispatchThreadMode

enum crinitDispatchThreadMode

Type to describe wheter the spawn thread launches start or stop commands

Enumerator
CRINIT_DISPATCH_THREAD_MODE_START
CRINIT_DISPATCH_THREAD_MODE_STOP

Function Documentation

◆ crinitTaskDBAddDepToTask()

int crinitTaskDBAddDepToTask	(	crinitTaskDB_t *	ctx,
		const crinitTaskDep_t *	dep,
		const char *	taskName
	)

Add a dependency to a specific task inside a task database.

Will search ctx for a task with name taskName and add dep to its crinitTask_t::deps and adjust crinitTask_t::depsSize.

Modifies errno.

Parameters

ctx	The crinitTaskDb context to work on.
dep	The dependency to be added.
taskName	The name of the relevant task.

Returns: 0 on success, -1 otherweise

◆ crinitTaskDBBorrowTask()

crinitTask_t * crinitTaskDBBorrowTask	(	crinitTaskDB_t *	ctx,
		const char *	taskName
	)

Provide direct thread-safe access to a task within a task database

If a task with the given name is found within the task database context, the calling thread will hold an exclusive lock on the context and get a reference to the task in question via return value. After the calling thread has finished its operations on the global option storage, it must release the lock using crinitTaskDBRemit().

If the function returns an error (NULL), no database lock is acquired.

As the lock is held on the whole task database, operations in the critical section between crinitTaskDBBorrowTask and crinitTaskDBRemit() must be kept short to avoid performance issues.

Modifies errno.

Parameters

ctx	The TaskDB containing the task to borrow.
taskName	The name of the task to borrow.

Returns: A pointer to the task with taskName within the task database context on success, NULL on any error.

◆ crinitTaskDBDestroy()

int crinitTaskDBDestroy ( crinitTaskDB_t * ctx )

Free memory allocated for crinitTaskDB_t members by functions like crinitTaskDBInit or crinitTaskDBInsert().

Afterwards ctx may not be used anymore until another call to crinitTaskDBInit() or crinitTaskDBInitWithSize().

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context to be destroyed.

Returns: 0 on success, -1 on error

◆ crinitTaskDBExportTaskNamesToArray()

int crinitTaskDBExportTaskNamesToArray	(	crinitTaskDB_t *	ctx,
		char **	tasks[],
		size_t *	numTasks
	)

Export the list of task names currently in the task database.

The function allocates an array of strings as tasks and returns the number of array elements in numTasks. Each entry in the tasks array will be allocated separately and needs to be freed by the caller.

Modifies errno.

Parameters

ctx	The TaskDB context from which to get the list of task names.
tasks	The return pointer for the array of task names.
numTasks	The return pointer for the number of array entries.

Returns: 0 on success, -1 on error

◆ crinitTaskDBFulfillDep()

int crinitTaskDBFulfillDep	(	crinitTaskDB_t *	ctx,
		const crinitTaskDep_t *	dep,
		crinitTask_t *	target
	)

Fulfill a dependency for all tasks inside a task database.

Will search ctx for tasks containing a dependency equal to dep (i.e. specifying the same name and event, according to strcmp()) and, if found, remove the dependency from crinitTask_t::deps. Will signal crinitTaskDB_t::changed on successful completion. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which to fulfill the dependency.
dep	The dependency to be fulfilled.
target	The targeted task or NULL.

Returns: 0 on success, -1 otherwise

◆ crinitTaskDBGetTaskByName()

int crinitTaskDBGetTaskByName	(	crinitTaskDB_t *	ctx,
		crinitTask_t **	task,
		const char *	taskName
	)

Find the task with the given name.

Modifies errno.

Parameters

ctx	The crinitTaskDb context to work on.
task	Pointer to hold the task.
taskName	The name of the relevant task.

Returns: 0 on success, -1 otherweise

◆ crinitTaskDBGetTaskPID()

int crinitTaskDBGetTaskPID	(	crinitTaskDB_t *	ctx,
		pid_t *	pid,
		const char *	taskName
	)

Get the PID of a task in a task database

Will search ctx for an crinitTask_t with crinitTask_t::name lexicographically equal to taskName and write its PID to pid. If such a task does not exit in ctx, an error is returned. If the task does not currently have a running process, pid will be -1 but the function will indicate success. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which the task is held.
pid	Pointer to store the returned PID.
taskName	The task's name.

Returns: 0 on success, -1 otherwise.

◆ crinitTaskDBGetTaskState()

int crinitTaskDBGetTaskState	(	crinitTaskDB_t *	ctx,
		crinitTaskState_t *	s,
		const char *	taskName
	)

Get the crinitTaskState_t of a task in a task database

Will search ctx for an crinitTask_t with crinitTask_t::name lexicographically equal to taskName and write its crinitTask_t::state to s. If such a task does not exist in ctx, an error is returned. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which the task is held.
s	Pointer to store the returned crinitTaskState_t.
taskName	The task's name.

Returns: 0 on success, -1 otherwise.

◆ crinitTaskDBGetTaskStateAndPID()

int crinitTaskDBGetTaskStateAndPID	(	crinitTaskDB_t *	ctx,
		crinitTaskState_t *	s,
		pid_t *	pid,
		const char *	taskName
	)

Get the crinitTaskState_t and the PID of a task in a task database

Will search ctx for an crinitTask_t with crinitTask_t::name lexicographically equal to taskName and write its crinitTask_t::state to s and its PID to pid. If such a task does not exist in ctx, an error is returned. If the task does not currently have a running process, pid will be -1 but the function will indicate success. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which the task is held.
s	Pointer to store the returned crinitTaskState_t.
pid	Pointer to store the returned PID.
taskName	The task's name.

Returns: 0 on success, -1 otherwise.

◆ crinitTaskDBInitWithSize()

int crinitTaskDBInitWithSize	(	crinitTaskDB_t *	ctx,
		int()(crinitTaskDB_t ctx, const crinitTask_t *, crinitDispatchThreadMode_t mode)	spawnFunc,
		size_t	initialSize
	)

Initialize the internals of an crinitTaskDB_t with a specified initial size for crinitTaskDB_t::taskSet.

If the initialized TaskDB is no longer needed the internally held dynamic memory should be freed using crinitTaskDBDestroy().

Modifies errno.

Parameters

ctx	The crinitTaskDB_t whose internal members should be initialized.
spawnFunc	Pointer to the task spawn function to be used by crinitTaskDBSpawnReady()
initialSize	Initial size of crinitTaskDB_t::taskSet for ctx.

Returns: 0 on success, -1 otherwise

◆ crinitTaskDBInsert()

int crinitTaskDBInsert	(	crinitTaskDB_t *	ctx,
		const crinitTask_t *	t,
		bool	overwrite
	)

Insert a task into a task database.

Will store a copy of t in the crinitTaskDB_t::taskSet of ctx. crinitTaskDB_t::taskSetItems will be incremented and if crinitTaskDB_t::taskSetSize is not sufficient, the set will be grown. If overwrite is true, a task with the same name in the set will be overwritten. If it is false, an existing task with the same name will cause an error. If the task has been successfully inserted, the function will signal crinitTaskDB_t::changed. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context, into which task should be inserted.
t	The task to be inserted.
overwrite	Overwrite a colliding task with the same name (true) or return an error (false).

Returns: 0 on success, -1 otherwise

◆ crinitTaskDBProvideFeature()

int crinitTaskDBProvideFeature	(	crinitTaskDB_t *	ctx,
		const crinitTask_t *	provider,
		crinitTaskState_t	newState
	)

Fulfill feature dependencies implemented by a provider task.

Will search ctx for tasks containing feature dependencies PROVIDE-ed by provider given its new state newState and, if found, remove the dependency from crinitTask_t::dep by using crinitTaskDBFulfillDep(). Synchronization and signalling remains the same as with a direct call to crinitTaskDBFulfillDep().

Parameters

ctx	The crinitTaskDB_t context in which to fulfill the feature dependency.
provider	The crinitTask_t providing the feature(s).
newState	The crinitTaskState_t which has been newly reached by provider.

Returns: 0 on success, -1 otherwise

◆ crinitTaskDBProvideFeatureByTaskName()

int crinitTaskDBProvideFeatureByTaskName	(	crinitTaskDB_t *	ctx,
		const char *	taskName,
		crinitTaskState_t	newState
	)

Fulfill feature dependencies implemented by a provider task (searched for by name).

Will search ctx for the provider task referenced by taskName and then call crinitTaskDBProvideFeature() on it (see there for details).

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which to fulfill the feature dependency.
taskName	The name of the task providing the feature(s).
newState	The crinitTaskState_t which has been newly reached by the provider task.

Returns: 0 on success, -1 otherwise

◆ crinitTaskDBRemit()

int crinitTaskDBRemit ( crinitTaskDB_t * ctx )

Release the lock on the task database acquired via crinitTaskDBBorrowTask(). The borrowed task reference may not be used anymore.

Modifies errno.

Parameters

ctx	The TaskDB to release the lock from.

Returns: 0 on success, -1 if the lock could not be released.

◆ crinitTaskDBRemoveDepFromTask()

int crinitTaskDBRemoveDepFromTask	(	crinitTaskDB_t *	ctx,
		const crinitTaskDep_t *	dep,
		const char *	taskName
	)

Remove a dependency from a specific task inside a task database.

Will search ctx for a task with name taskName and remove a dependency equal to dep from its crinitTask_t::deps and adjust crinitTask_t::depsSize, if such a dependency is present. The equality condition between two crinitTaskDep_t instances is the same as in crinitTaskDBFulfillDep(), i.e. their contents are lexicographically equal.

Modifies errno.

Parameters

ctx	The crinitTaskDb context to work on.
dep	The dependency to be removed.
taskName	The name of the relevant task.

Returns: 0 on success, -1 otherweise

◆ crinitTaskDBSetSpawnInhibit()

int crinitTaskDBSetSpawnInhibit	(	crinitTaskDB_t *	ctx,
		bool	inh
	)

Inhibit or un-inhibit spawning of processes by setting crinitTaskDB_t::spawnInhibit.

The function uses crinitTaskDB_t::lock for synchronization and is thread-safe. It will also signal crinitTaskDB_t::changed if crinitTaskDB_t::spawnInhibit was changed to false.

Modifies errno.

Parameters

ctx	The TaskDB context in which to set the variable.
inh	The value which crinitTaskDB_t:spawnInhibit shall be set to.

Returns: 0 on success, -1 otherwise

◆ crinitTaskDBSetTaskPID()

int crinitTaskDBSetTaskPID	(	crinitTaskDB_t *	ctx,
		pid_t	pid,
		const char *	taskName
	)

Set the PID a task in a task database

Will search ctx for an crinitTask_t with crinitTask_t::name lexicographically equal to taskName and set its crinitTask_t::pid to pid. If such a task does not exit in ctx, an error is returned. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which the task is held.
pid	The task's new PID.
taskName	The task's name.

Returns: 0 on success, -1 otherwise.

◆ crinitTaskDBSetTaskRespawnInhibit()

int crinitTaskDBSetTaskRespawnInhibit	(	crinitTaskDB_t *	ctx,
		bool	inhibit,
		const char *	taskName
	)

Sets the respawnInhibit flag.

Prevents the respawning of a task that was configured with "RESPAWN = yes". Used in conjunction with crinit-ctl stop.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which the task is held.
inhibit	If true, do not respawn the task. Otherwise continue with normal behaviour.
taskName	The task's name.

Returns: 0 on success, -1 otherwise.

◆ crinitTaskDBSetTaskState()

int crinitTaskDBSetTaskState	(	crinitTaskDB_t *	ctx,
		crinitTaskState_t	s,
		const char *	taskName
	)

Set the crinitTaskState_t of a task in a task database

Will search ctx for an crinitTask_t with crinitTask_t::name lexicographically equal to taskName and set its crinitTask_t::state to s. If such a task does not exist in ctx, an error is returned. If s equals CRINIT_TASK_STATE_FAILED, crinitTask_t::failCount will be incremented by 1. If s equals CRINIT_TASK_STATE_DONE, crinitTask_t::failCount will be reset to 0. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which the task is held.
s	The task's new state.
taskName	The task's name.

Returns: 0 on success, -1 otherwise.

◆ crinitTaskDBSpawnReady()

int crinitTaskDBSpawnReady	(	crinitTaskDB_t *	ctx,
		crinitDispatchThreadMode_t	mode
	)

Run crinitTaskDB_t::spawnFunc for each startable task in a task database.

A task is startable if and only if it has no remaining crinitTask_t::deps and it has either not been started before according to crinitTask_t::state or it should be respawned. A task should be respawned if and only if crinitTask_t::opts contains the flag CRINIT_TASK_OPT_RESPAWN and either crinitTask_t::maxRetries is -1 or crinitTask_t::failCount is less than crinitTask_t::maxRetries. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

If crinitTaskDB::spawnInhibit is true, no tasks are considered startable and this function will return successfully without starting anything.

Modifies errno.

Parameters

ctx	The TaskDB context from which tasks will be started.
mode	Distinguishes between start and stop commands

Returns: 0 on success, -1 otherwise

◆ crinitTaskRearmTrigger()

int crinitTaskRearmTrigger	(	crinitTaskDB_t *	ctx,
		const char *	taskName
	)

Rearm the triggeer of a task in a task database

Will search ctx for a crinitTask_t with crinitTask_t::name lexicographically equal to taskName, set its crinitTask_t::state to CRINIT_TASK_STATE_LOADED and reset all the trigger that require resetting. If such a task does not exist in ctx, an error is returned. The function uses crinitTaskDB_t::lock for synchronization and is thread-safe.

Modifies errno.

Parameters

ctx	The crinitTaskDB_t context in which the task is held.
taskName	The task's name.

Returns: 0 on success, -1 otherwise.

(/usr/bin/git)

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CRINIT_MONITOR_DEP_NAME

◆ CRINIT_PROVIDE_DEP_NAME

◆ CRINIT_TASKDB_INITIAL_SIZE

◆ crinitTaskDbForEach

◆ crinitTaskDBInit

◆ crinitTaskDBUpdate

Typedef Documentation

◆ crinitDispatchThreadMode_t

◆ crinitTaskDB_t

Enumeration Type Documentation

◆ crinitDispatchThreadMode

Function Documentation

◆ crinitTaskDBAddDepToTask()

◆ crinitTaskDBBorrowTask()

◆ crinitTaskDBDestroy()

◆ crinitTaskDBExportTaskNamesToArray()

◆ crinitTaskDBFulfillDep()

◆ crinitTaskDBGetTaskByName()

◆ crinitTaskDBGetTaskPID()

◆ crinitTaskDBGetTaskState()

◆ crinitTaskDBGetTaskStateAndPID()

◆ crinitTaskDBInitWithSize()

◆ crinitTaskDBInsert()

◆ crinitTaskDBProvideFeature()

◆ crinitTaskDBProvideFeatureByTaskName()

◆ crinitTaskDBRemit()

◆ crinitTaskDBRemoveDepFromTask()

◆ crinitTaskDBSetSpawnInhibit()

◆ crinitTaskDBSetTaskPID()

◆ crinitTaskDBSetTaskRespawnInhibit()

◆ crinitTaskDBSetTaskState()

◆ crinitTaskDBSpawnReady()

◆ crinitTaskRearmTrigger()