Files
file	esos_task.h

Data Structures
struct	stSemaphore

struct	ESOS_TASK_HANDLE

Initialization
#define	__ESOS_INIT_TASK(TaskHandle)

Querying the state of a task
#define	ESOS_IS_TASK_INITED(TaskHandle)

#define	ESOS_IS_TASK_SLEEPING(TaskHandle)

#define	ESOS_IS_TASK_KILLED(TaskHandle)

#define	ESOS_IS_TASK_WAITING(TaskHandle)

#define	ESOS_IS_TASK_ENDED(TaskHandle)

Declaration and definition
#define	ESOS_USER_TASK(taskname)

#define	ESOS_CHILD_TASK(taskname, ...)

#define	ESOS_TASK_BEGIN()

#define	ESOS_TASK_END()

#define	ESOS_TASK_GET_TASK_HANDLE()

Calling an ESOS task
#define	ESOS_SCHEDULE_TASK(pfnThread)

Blocked waits
#define	ESOS_TASK_WAIT_UNTIL(condition)

#define	ESOS_TASK_WAIT_WHILE(cond)

#define	ESOS_TASK_WAIT_TICKS(u32_duration)

Tasks and child tasks
#define	ESOS_TASK_WAIT_THREAD(pfnChild, ...)

#define	ESOS_TASK_SPAWN_AND_WAIT(pstChild, pfnChild, ...)

#define	ESOS_ALLOCATE_CHILD_TASK(pstName)

Sleeping, killing, exiting and restarting tasks
#define	ESOS_TASK_SLEEP()

#define	ESOS_TASK_RESTART()

#define	ESOS_TASK_EXIT()

#define	ESOS_WAKE_TASK(TaskHandle)

#define	ESOS_KILL_TASK(TaskHandle)

#define	ESOS_RESTART_TASK(TaskHandle)

Yielding from an ESOS task
#define	ESOS_TASK_YIELD()

Task semaphores
#define	ESOS_SEMAPHORE(semaphoreName)

#define	ESOS_INIT_SEMAPHORE(semaphoreName, i16_val)

#define	ESOS_TASK_WAIT_SEMAPHORE(semaphoreName, i16_val)

#define	ESOS_SIGNAL_SEMAPHORE(semaphoreName, i16_val)

Detailed Description

Macro Definition Documentation

◆ __ESOS_INIT_TASK

#define __ESOS_INIT_TASK ( TaskHandle )

Initialize an ESOS task.

Initializes an ESOS task. Initialization must be done prior to starting to execute the task.

Note: Called by ESOS internally. Users have no real reason to call this function themselves.

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task to be initialized

See also: ESOS_TASK_SPAWN_AND_WAIT; ESOS_TASK_GET_TASK_HANDLE

Definition at line 143 of file esos_task.h.

◆ ESOS_ALLOCATE_CHILD_TASK

#define ESOS_ALLOCATE_CHILD_TASK ( pstName )

Allocates a child task storage structure in the local stack frame.

This macro spawns a child ESOS task and waits until it exits. The macro can only be used within an ESOS task.

Parameters

pstName Name of variable to represent the allocated child task structure

Definition at line 448 of file esos_task.h.

◆ ESOS_CHILD_TASK

#define ESOS_CHILD_TASK	(	taskname,
		...
	)

Declaration of an ESOS child task – a task spawned by another ESOS task (a.k.a. the parent task)

This macro is used to declare an ESOS child task. All ESOS child tasks must be declared with this macro. This macro relies on the compiler's ability to handle variadic arguments. GCC does this just fine. Other compilers may not work.

Note: ESOS child tasks can have zero or more input arguments passed in. However, ESOS child tasks cannot return values.

Parameters

taskname	The name by which you wish for the child task to be known. In reality, this name is the name of a C function implementing the ESOS child task.
...	(OPTIONAL) Any arguments to pass to the the child task

Definition at line 247 of file esos_task.h.

Referenced by esos_pic24_configI2C1().

◆ ESOS_INIT_SEMAPHORE

#define ESOS_INIT_SEMAPHORE	(	semaphoreName,
		i16_val
	)

Initialize a semaphore

This macro initializes a semaphore with a value for the counter. Internally, the semaphores use an "signed 16 bit integer" to represent the counter, and therefore the "count" argument should be between -32768 and +32767

Parameters

semaphoreName	An ESOS semaphore created by ESOS_SEMAPHORE
i16_val	(int16_t) The initial count of the semaphore.

See also: ESOS_SEMAPHORE; ESOS_TASK_WAIT_SEMAPHORE; ESOS_SIGNAL_SEMAPHORE

Definition at line 650 of file esos_task.h.

◆ ESOS_IS_TASK_ENDED

#define ESOS_IS_TASK_ENDED ( TaskHandle )

Determines if a task is inactive/ended. Tasks in this state are subject to culling by the ESOS scheduler at some point in future.

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task being queried

See also: ESOS_TASK_GET_TASK_HANDLE

Definition at line 205 of file esos_task.h.

◆ ESOS_IS_TASK_INITED

#define ESOS_IS_TASK_INITED ( TaskHandle )

Is ESOS task structure initialized?.

Checks to see of the ESOS task structure is initialized. Initialization must be done prior to starting to execute the task. In reality, this checks to see if a task structure is available since a 'running' task structure will appear to be uninitialized since its state will not be NULL, ZERO, or whatever our implementation of uses as the initial state.

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task being queried

See also: __ESOS_INIT_TASK

Definition at line 167 of file esos_task.h.

Referenced by esos_GetFreeChildTaskStruct().

◆ ESOS_IS_TASK_KILLED

#define ESOS_IS_TASK_KILLED ( TaskHandle )

Determines if a task is slated to be killed at its next execution.

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task being queried

See also: ESOS_TASK_GET_TASK_HANDLE

Definition at line 185 of file esos_task.h.

◆ ESOS_IS_TASK_SLEEPING

#define ESOS_IS_TASK_SLEEPING ( TaskHandle )

Determines if a task is currently sleeping

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task being queried

See also: ESOS_TASK_GET_TASK_HANDLE

Definition at line 176 of file esos_task.h.

◆ ESOS_IS_TASK_WAITING

#define ESOS_IS_TASK_WAITING ( TaskHandle )

Determines if a task is waiting to run/blocked by some condition.

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task being queried

See also: ESOS_TASK_GET_TASK_HANDLE

Definition at line 194 of file esos_task.h.

◆ ESOS_KILL_TASK

#define ESOS_KILL_TASK ( TaskHandle )

Kill an scheduled ESOS task.

This macro will cause the target task to "die" (exit) at its next scheduled execution. The target task will not execute any more instructions.

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task to kill

See also: ESOS_TASK_GET_TASK_HANDLE

Definition at line 547 of file esos_task.h.

◆ ESOS_RESTART_TASK

#define ESOS_RESTART_TASK ( TaskHandle )

Restart a scheduled ESOS task

This macro will cause the target task to "restart" (run from the beginning as if it were just created) at its next scheduled execution.

Note: Anything the target task has done and all of its local data variables and states will likely be lost. Do NOT restart another task unless you are very sure of how it will respond.

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task to kill

See also: ESOS_TASK_GET_TASK_HANDLE

Definition at line 565 of file esos_task.h.

◆ ESOS_SCHEDULE_TASK

#define ESOS_SCHEDULE_TASK ( pfnThread )

Schedule an ESOS task.

This function schedules an ESOS task. The return value of the function is non-zero if the ESOS task is running or zero if the ESOS task has exited.

Note: Typically, this macro is only called by other ESOS task macros and the ESOS task scheduler. I can't think of any reasonable reason why an user would need to call this macro!

Parameters

pfnThread The call to the C function implementing the ESOS task to be scheduled

Definition at line 314 of file esos_task.h.

◆ ESOS_SEMAPHORE

#define ESOS_SEMAPHORE ( semaphoreName )

Declare (and create storage for) an ESOS counting semaphore

Parameters

semaphoreName The name by which the semaphore is to be known

Note: Declares the memory storage space along with the ESOS_SEMAPHORE "object" that is used by user code.; Since semaphores are typically used for synchronization, this macro to allocate storage for a semaphore should almost always be used in the "global" variable section of your application.

Todo:: Make sure semaphores are safe in ISRs. Probably need to make semaphore storage and associated macros volatile

Definition at line 632 of file esos_task.h.

◆ ESOS_SIGNAL_SEMAPHORE

#define ESOS_SIGNAL_SEMAPHORE	(	semaphoreName,
		i16_val
	)

Signal a semaphore

This macro carries out the "signal" operation on the semaphore. The signal operation increments the counter inside the semaphore, which eventually will cause waiting protothreads to continue executing.

Parameters

semaphoreName	An ESOS semaphore created by ESOS_SEMAPHORE
i16_val	(int16_t) number to decrement semaphore value

See also: ESOS_SEMAPHORE; ESOS_TASK_WAIT_SEMAPHORE; ESOS_INIT_SEMAPHORE

Definition at line 687 of file esos_task.h.

◆ ESOS_TASK_BEGIN

#define ESOS_TASK_BEGIN ( )

Declare the start of an ESOS task inside the C function implementing the ESOS task.

This macro is used to declare the starting point of a ESOS task. It should be placed at the start of the function in which the ESOS task runs. All C statements above the ESOS_TASK_BEGIN() invokation will be executed each time the ESOS task is scheduled.

See also: ESOS_TASK_END

Definition at line 260 of file esos_task.h.

Referenced by ESOS_CHILD_TASK(), esos_pic24_configI2C1(), and ESOS_USER_TASK().

◆ ESOS_TASK_END

#define ESOS_TASK_END ( )

Declare the end of an ESOS task.

This macro is used for declaring that an ESOS task ends. It must always be used together with a matching ESOS_TASK_BEGIN() macro.

See also: ESOS_TASK_BEGIN

Definition at line 272 of file esos_task.h.

Referenced by ESOS_CHILD_TASK(), and esos_pic24_configI2C1().

◆ ESOS_TASK_EXIT

#define ESOS_TASK_EXIT ( )

Exit the current ESOS task.

This macro causes the current ESOS task to exit. If the ESOS task was spawned by another ESOS task, the parent ESOS task will become unblocked and can continue to run.

See also: ESOS_TASK_SPAWN; ESOS_TASK_WAIT_THREAD

Definition at line 513 of file esos_task.h.

◆ ESOS_TASK_GET_TASK_HANDLE

#define ESOS_TASK_GET_TASK_HANDLE ( )

Retrieve the task handle for the current task.

This macro gets the task handle for the current task. Useful if the current task wishes to give its handle to some other task so that the other task can manipulate the current task externally.

See also: ESOS_TASK_WAKE; ESOS_TASK_KILL

Definition at line 290 of file esos_task.h.

◆ ESOS_TASK_RESTART

#define ESOS_TASK_RESTART ( )

Restart the current ESOS task.

This macro will block the current and cause the task to restart its execution at the place of the ESOS_TASK_BEGIN() call at its next scheduled execution time.

Definition at line 494 of file esos_task.h.

◆ ESOS_TASK_SLEEP

#define ESOS_TASK_SLEEP ( )

Put the current task to sleep.

This macro will cause the current task to "sleep" (block) until the task is awakened. The current task will not execute until it is explicitly wakened by some task caliing ESOS_WAKE_TASK with the target task's identifier. The sleeping task will resume execution at the instruction following the ESOS_TASK_SLEEP().

See also: ESOS_WAKE_TASK

Definition at line 479 of file esos_task.h.

◆ ESOS_TASK_SPAWN_AND_WAIT

#define ESOS_TASK_SPAWN_AND_WAIT	(	pstChild,
		pfnChild,
		...
	)

This macro initializes an ESOS child task structure, calls the child task and blocks the parent task until the child exits exits. The macro can only be used within an ESOS task.

Parameters

pstChild	Pointer to the child ESOS task's control structure.
pfnChild	Pointer to the child task function
...	Arguments to the child task (if they exist)

See also: ESOS_TASK_WAIT_THREAD; ESOS_CHILD_TASK

Note: Child task should have been defined with ESOS_CHILD_TASK; Child task structure should have been obtained with ESOS_ALLOCATE_CHILD_TASK

Definition at line 436 of file esos_task.h.

◆ ESOS_TASK_WAIT_SEMAPHORE

#define ESOS_TASK_WAIT_SEMAPHORE	(	semaphoreName,
		i16_val
	)

Wait for a semaphore

This macro carries out the "wait" operation on the semaphore. The wait operation causes the current ESOS task to block while the counter is zero. When the counter reaches a value larger than zero, the task will continue.

Parameters

semaphoreName	An ESOS semaphore created by ESOS_SEMAPHORE
i16_val	(int16_t) number to decrement semaphore value

See also: ESOS_SEMAPHORE; ESOS_INIT_SEMAPHORE; ESOS_SIGNAL_SEMAPHORE

Definition at line 667 of file esos_task.h.

◆ ESOS_TASK_WAIT_THREAD

#define ESOS_TASK_WAIT_THREAD	(	pfnChild,
		...
	)

Block and wait until a child ESOS task completes.

This macro schedules a child ESOS task. The current ESOS task will block until the child ESOS task completes.

Todo:: I THINK THIS SHOULD BE REWRITTEN TO USE THE ESOS TASK STATE VARIABLES INSTEAD OF A CALL TO ESOS_SCHEDULE_TASK. DOESN'T WORK FOR BOTH PARENT AND CHILD TASKS AS WRITTEN!

Note: The child ESOS task must be manually initialized with the __ESOS_INIT_TASK function before this function is used.; Child task should have been defined with ESOS_CHILD_TASK

Parameters

pfnChild	Pointer to the child task function
...	Arguments to the child task (if they exist)

See also: ESOS_TASK_SPAWN_AND_WAIT; ESOS_CHILD_TASK

Definition at line 419 of file esos_task.h.

◆ ESOS_TASK_WAIT_TICKS

#define ESOS_TASK_WAIT_TICKS ( u32_duration )

Block and wait for a period of time/ticks

This function blocks and waits for the duration of time requested.

Parameters

u32_duration Number of system ticks (currently milliseconds) to block

Definition at line 376 of file esos_task.h.

◆ ESOS_TASK_WAIT_UNTIL

#define ESOS_TASK_WAIT_UNTIL ( condition )

Block and wait until condition is true.

This macro blocks the ESOS task until the specified condition is true.

Parameters

condition The condition.

See also: ESOS_TASK_WAIT_WHILE

Definition at line 336 of file esos_task.h.

Referenced by esos_pic24_configI2C1().

◆ ESOS_TASK_WAIT_WHILE

#define ESOS_TASK_WAIT_WHILE ( cond )

Block and wait while condition is true.

This function blocks and waits while the specified condition is true.

Parameters

cond	The condition.

See also: ESOS_TASK_WAIT_UNTIL

Definition at line 364 of file esos_task.h.

Referenced by ESOS_CHILD_TASK(), and esos_pic24_configI2C1().

◆ ESOS_TASK_YIELD

#define ESOS_TASK_YIELD ( )

Yield the current ESOS task.

This function will yield the ESOS task IMMEDIATELY, thereby allowing other processing to take place in the system. The task will resume at the next instruction at its next invocation by the scheduler. (Of course, another task may "kill" it in the meantime and the task will not run again.)

Definition at line 590 of file esos_task.h.

◆ ESOS_USER_TASK

#define ESOS_USER_TASK ( taskname )

Declaration of an ESOS task.

This macro is used to declare an ESOS task. All ESOS tasks must be declared with this macro.

Note: ESOS tasks have no arguments passed in and cannot return values.

Parameters

taskname The name by which you wish for the user task to be known. In reality, this name is the name of the C function implementing the ESOS task. Therefore, your task names must be unique and adhere to C language naming restrictions.

Definition at line 228 of file esos_task.h.

◆ ESOS_WAKE_TASK

#define ESOS_WAKE_TASK ( TaskHandle )

Wake up a sleeping ESOS task.

This macro will cause the target task to "wake" (resume) at its next opportunity. The sleeping task will resume execution at the instruction following the ESOS_TASK_SLEEP that initially put the task to sleep.

Parameters

TaskHandle The ESOS_TASK_HANDLE of the task to wake up.

See also: ESOS_TASK_GET_TASK_HANDLE; ESOS_TASK_SLEEP

Definition at line 534 of file esos_task.h.

Files

Data Structures

Initialization

Querying the state of a task

Declaration and definition

Calling an ESOS task

Blocked waits

Tasks and child tasks

Sleeping, killing, exiting and restarting tasks

Yielding from an ESOS task

Task semaphores

Detailed Description

Macro Definition Documentation

◆ __ESOS_INIT_TASK

◆ ESOS_ALLOCATE_CHILD_TASK

◆ ESOS_CHILD_TASK

◆ ESOS_INIT_SEMAPHORE

◆ ESOS_IS_TASK_ENDED

◆ ESOS_IS_TASK_INITED

◆ ESOS_IS_TASK_KILLED

◆ ESOS_IS_TASK_SLEEPING

◆ ESOS_IS_TASK_WAITING

◆ ESOS_KILL_TASK

◆ ESOS_RESTART_TASK

◆ ESOS_SCHEDULE_TASK

◆ ESOS_SEMAPHORE

◆ ESOS_SIGNAL_SEMAPHORE

◆ ESOS_TASK_BEGIN

◆ ESOS_TASK_END

◆ ESOS_TASK_EXIT

◆ ESOS_TASK_GET_TASK_HANDLE

◆ ESOS_TASK_RESTART

◆ ESOS_TASK_SLEEP

◆ ESOS_TASK_SPAWN_AND_WAIT

◆ ESOS_TASK_WAIT_SEMAPHORE

◆ ESOS_TASK_WAIT_THREAD

◆ ESOS_TASK_WAIT_TICKS

◆ ESOS_TASK_WAIT_UNTIL

◆ ESOS_TASK_WAIT_WHILE

◆ ESOS_TASK_YIELD

◆ ESOS_USER_TASK

◆ ESOS_WAKE_TASK