weAut_01 / weAutSys    R 2.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Data Fields
mThr_data_t Struct Reference

Data Fields

uint8_t flag
 A flag byte for the threads specific usage.
p2ptFun fun
 The thread's function (pointer to)
pt_t pt
 The (raw) protothread data structure.
uint8_t retC
 The return code of the last schedule.

Detailed Description

State data for a thread (minimal)

It is strongly recommended that threads use this structure for their essential state. The thread function's (the behaviour) recommended signature takes (only) a pointer to such structure as parameter.

Software using this schema is supported by some handling functions and macros provided. If more state info is required the extended type thr_data_t should be used; it can be cast back to this common smaller type mThr_data_t to use the appropriate handling functions.

See also:
resetAppThread
scheduleAppThread
scheduleRegdAppThread
scheduleFlgdAppThread
scheduleYldAppThread
registerAppThread(struct mThr_data_t *, p2ptFun)
initSetAppThread(struct mThr_data_t *, p2ptFun)
Examples:
main.c.

Field Documentation

uint8_t flag

A flag byte for the threads specific usage.

This is intended to hold (additionally to pt) the primary thread state. The semantic is defined by the thread function (the behaviour).

Insofar the thread implementation (i.e. the thread function code) is totally free with respect to this flag's semantic. The only fixed common convention is
  0 : "no work to do" for the thread
This convention should be strictly observed, as weAutSys may not schedule a thread on !flag.

flag is used as workload count for cyclic threads respectively periodic tasks in weAutSys; that means something like
  0 : "do no periodic work even if scheduled"
  1 : "do normal periodic work"
  2.. means cycle overrun "do the work of 2.. periods"

As said above, the value 0 meaning "nothing to do" is the only rule never to be violated.

Examples:
main.c.
uint8_t retC

The return code of the last schedule.

This is intended as a secondary status flag. The recommended (and supported) use is to hold the thread function's last return value.

Hint: Some supporting functions and macros use this retC to treat a yielding thread in a special way: it might be scheduled with flag == 0 for doing rest work but a blocking thread will not. Their criterion is just retC == PT_YIELDED

The thread's function (pointer to)

The function must implement a thread (behaviour) according to all Protothreads and weAutSys rules therefore. This pointer is binding this thread state to a thread function.

Hint / rationale: It is quite possible to have one thread function handle multiple thread objects implementing a common behaviour. This function must keep all thread state in the thread structure. But to have this state data never in in any other (static) variables is good practice anyway.

The other way round is never feasible: no living Protothread can be handled by more than one thread function at the same time.
Hence it is quite logical to (optionally) register this one / current thread function here.

This being NULL may hence mean this thread having no registered function respectively behaviour.

Hint 2: If the Protothread function is statically fixed for a set of threads (and none of the above mentioned scheduling macros is used on them) this fun pointer may be used for other purposes.


The documentation for this struct was generated from the following file: