ECROS API Function OsTaskBindFunction()

OsResultE OsTaskBindFunction( OsHndlT task, OsTaskFuncF function );

Function OsTaskBindFunction() must be called by the client application to bind a task function to a task.  This will then be the function called by the ECROS scheduler when the task is run.  The first argument is a handle to the task, obtained from OsNewTask().  If this task handle is invalid, no action is taken and the function returns OsResult_INVALID_HANDLE.  The second argument is the address of the task function to be bound to the task.  The task function must be compatible with the function pointer type OsTaskFuncF.  That is, it must take a single argument of type OsEventsT and return nothing.  If the task function address supplied is zero, the task is bound to an error task function supplied by ECROS and an error will be indicated if the task should ever run.

Example

The example below shows the creation of a new task and the binding to it of a task function.  The task function MyTask()must be defined elsewhere in the application and the prototype must be available to the compiler to check for compatibility with the function pointer type OsTaskFuncF.

OsHndlT task;

task = OsNewTask( OsPrior_MEDIUM );
if ( task != OS_TASK_NONE )
   OsTaskBindFunction( task, MyTask );

Advanced

As well as binding a task function to a task upon creation of that task, OsTaskBindFunction() can be used to:

• change the task function bound to a task and therefore change what happens when a task runs
• unbind the task from any task function (by supplying a zero address as the second argument) when the task should not run according to the application design (for example, its work is complete)

If the task function bound to a task is changed or unbound while that task is running, there will be no effect until the next time the task runs.  The new task function is not run as part of the current invocation of the task.

Tip - a good implementation of a state machine is a task that changes its task function according to state.  Each function processes the state machine inputs as required for that state and performs any necessary state change, including binding a new task function to the task, before returning.  Common operations can be factored out as sub-functions and called from the task functions for each state in which they are required.