COSA
An Object-Oriented Platform for Arduino Programming
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
ProtoThread Class Referenceabstract

#include <ProtoThread.hh>

Inheritance diagram for ProtoThread:
Inheritance graph
Collaboration diagram for ProtoThread:
Collaboration graph

Public Types

enum  {
  INITIATED = 0, READY, WAITING, TIMEOUT,
  RUNNING, SLEEPING, TERMINATED = 0xff
}
 

Public Member Functions

 ProtoThread (Job::Scheduler *scheduler)
 
bool begin ()
 
void end ()
 
uint8_t state () const
 
void set_timer (uint16_t ms)
 
void cancel_timer ()
 
bool timer_expired () const
 
virtual void on_run (uint8_t type, uint16_t value)=0
 
void expire_at (uint32_t time)
 
uint32_t expire_at () const
 
void expire_after (uint32_t time)
 
int32_t expire_after () const
 
uint32_t time () const
 
bool is_started () const
 
bool start ()
 
bool stop ()
 
virtual void on_expired ()
 
virtual void run ()
 
void detach ()
 
Linkage * succ () const
 
Linkage * pred () const
 
void attach (Linkage *pred)
 

Static Public Member Functions

static uint16_t dispatch (bool flag=true)
 
static void schedule (ProtoThread *thread)
 

Protected Member Functions

virtual void on_event (uint8_t type, uint16_t value)
 

Protected Attributes

uint8_t m_state
 
void * m_ip
 
uint32_t m_expires
 
Scheduler * m_scheduler
 
Linkage * m_succ
 
Linkage * m_pred
 

Static Protected Attributes

static Head runq
 

Detailed Description

Cosa implementation of protothreads; A protothread is a low-overhead mechanism for concurrent programming. Protothreads function as stackless, lightweight threads providing a blocking context using minimal memory per protothread. Cosa/Thread supports event to thread mapping and timers.

Limitations

The thread macro set should only be used within the ProtoThread::on_run() function. The macros cannot be used in functions called from on_run().

Acknowledgements

Inspired by research and prototype by Adam Dunkels, Oliver Schmidt, Thiermo Voigt, Muneeb Ali, and the protothread library by Larry Ruane.

References

[1] Adam Dunkels et al, Protothreads: Simplifying Event-Driven Programming of Memory-Constrained Embedded Systems, SenSys'06, November 1-3, 2006, Boulder, Colorado, USA.
[2] Larry Ruane, protothread: An extremely lightweight thread library for GCC, http://code.google.com/p/protothread/
[3] http://en.wikipedia.org/wiki/Protothreads

Definition at line 52 of file ProtoThread.hh.

Member Enumeration Documentation

anonymous enum

Thread states.

Enumerator
INITIATED 

Constructor.

READY 

In run queue.

WAITING 

In timer queue.

TIMEOUT 

Timeout received and running.

RUNNING 

Dispatched and running.

SLEEPING 

Detached. Need wakeup call.

TERMINATED 

Removed from all queues.

Definition at line 57 of file ProtoThread.hh.

Constructor & Destructor Documentation

ProtoThread::ProtoThread ( Job::Scheduler *  scheduler)
inline

Construct thread, initiate state and continuation. Does not schedule the thread. This is done with begin().

Parameters
[in]schedulerwiht milli-seconds time unit.

Definition at line 72 of file ProtoThread.hh.

Member Function Documentation

void Linkage::attach ( Linkage *  pred)
inlineinherited

Attach given linkage as predecessor. Will check and detach if already attached.

Parameters
[in]predlinkage to attach.
Note
atomic

Definition at line 71 of file Linkage.hh.

bool ProtoThread::begin ( )
inline

Start the thread. Must be in INITIATED state to be allowed to be scheduled. Returns false if not in correct state.

Returns
bool true if scheduled otherwise false.

Definition at line 83 of file ProtoThread.hh.

void ProtoThread::cancel_timer ( )
inline

Cancel timer and dequeue thread from timer queue.

Definition at line 126 of file ProtoThread.hh.

void Link::detach ( )
inlineinherited

Detach this link. Unlink from any list.

Definition at line 125 of file Linkage.hh.

uint16_t ProtoThread::dispatch ( bool  flag = true)
static

Run threads in the run queue. If given flag is true events will be processes. Returns number of dispatched threads and events. The run queue is only iterated once per call to dispatch to allow user defined outer loop, i.e., arduino loop() function.

Parameters
[in]flagprocess events if non zero.
Returns
number of dispatched threads and events.

Definition at line 41 of file ProtoThread.cpp.

void ProtoThread::end ( )
inline

End the thread. Mark as terminated and remove from any queue. Use macro THREAD_END() in thread body (run function).

Definition at line 94 of file ProtoThread.hh.

void Job::expire_after ( uint32_t  time)
inlineinherited

Set expire time relative to latest expire time.

Parameters
[in]timeto add to latest expire time.

Definition at line 111 of file Job.hh.

int32_t Job::expire_after ( ) const
inlineinherited

Get time remaining before expired.

Returns
time.

Definition at line 129 of file Job.hh.

void Job::expire_at ( uint32_t  time)
inlineinherited

Set expire time. Absolute time in scheduler time unit.

Parameters
[in]timeto expire.

Definition at line 102 of file Job.hh.

uint32_t Job::expire_at ( ) const
inlineinherited

Get expire time.

Returns
time.

Definition at line 120 of file Job.hh.

bool Job::is_started ( ) const
inlineinherited

Return true(1) if the job is queued otherwise false(0).

Returns
bool.

Definition at line 149 of file Job.hh.

void ProtoThread::on_event ( uint8_t  type,
uint16_t  value 
)
protectedvirtual

The first level event handler. Filters timeout events and run the thread action function.

Parameters
[in]typethe type of event.
[in]valuethe event value.

Reimplemented from Job.

Definition at line 27 of file ProtoThread.cpp.

virtual void Job::on_expired ( )
inlinevirtualinherited

Job member function that is called Scheduler::dispatch() when the job time has expired. This function is normally called from an interrupt service routine. The default implementation will push a timeout event with the job as target. The default event handler will call the job run() virtual member function. Override this function if the job should be executed during the interrupt service routine.

Definition at line 185 of file Job.hh.

virtual void ProtoThread::on_run ( uint8_t  type,
uint16_t  value 
)
pure virtual

Thread activity. Must be overridden. Use the thread macro set in the following format: { PROTO_THREAD_BEGIN(); while (1) { ... PROTO_THREAD_AWAIT(condition); ... } PROTO_THREAD_END(); } Additional macros are PROTO_THREAD_YIELD(), PROTO_THREAD_SLEEP(), PROTO_THREAD_WAKE(), and PROTO_THREAD_DELAY().

Parameters
[in]typethe type of event.
[in]valuethe event value.
Linkage* Linkage::pred ( ) const
inlineinherited

Return predecessor in sequence.

Returns
predecessor linkage.

Definition at line 60 of file Linkage.hh.

virtual void Job::run ( )
inlinevirtualinherited

The job run() virtual member function; sub-class should define. Called by the scheduler (via event handler) when the time expires. May set an new expire time and start the job again, or even start other jobs.

Reimplemented in Button, Keypad, and Touch.

Definition at line 210 of file Job.hh.

void ProtoThread::schedule ( ProtoThread *  thread)
static

Add the given thread to the run queue (last). A terminated thread may be restarted.

Parameters
[in]threadto enqueue.

Definition at line 78 of file ProtoThread.cpp.

void ProtoThread::set_timer ( uint16_t  ms)
inline

Set timer and enqueue thread to receive timeout event. If the timer expires the thread is put in TIMEOUT state.

Parameters
[in]mstimeout period.

Definition at line 114 of file ProtoThread.hh.

bool Job::start ( )
inlineinherited

Start the job. Returns true(1) if scheduled otherwise false(0).

Returns
bool.

Definition at line 159 of file Job.hh.

uint8_t ProtoThread::state ( ) const
inline

Get current thread state.

Returns
state.

Definition at line 104 of file ProtoThread.hh.

bool Job::stop ( )
inlineinherited

Stop the job. Returns true(1) if scheduled otherwise false(0).

Returns
bool.

Definition at line 169 of file Job.hh.

Linkage* Linkage::succ ( ) const
inlineinherited

Return successor in sequence.

Returns
successor linkage.

Definition at line 51 of file Linkage.hh.

uint32_t Job::time ( ) const
inlineinherited

Get current scheduler time. May be used to set relative expire time.

Returns
time.

Definition at line 139 of file Job.hh.

bool ProtoThread::timer_expired ( ) const
inline

Check if the timer expired; i.e., the thread is in TIMEOUT state.

Definition at line 136 of file ProtoThread.hh.

Member Data Documentation

uint32_t Job::m_expires
protectedinherited

Expire time. Scale (us, ms, s) depends on scheduler.

Definition at line 214 of file Job.hh.

void* ProtoThread::m_ip
protected

Definition at line 182 of file ProtoThread.hh.

Linkage* Linkage::m_pred
protectedinherited

Definition at line 94 of file Linkage.hh.

Scheduler* Job::m_scheduler
protectedinherited

Job scheduler.

Definition at line 217 of file Job.hh.

uint8_t ProtoThread::m_state
protected

Definition at line 181 of file ProtoThread.hh.

Linkage* Linkage::m_succ
protectedinherited

Double linked list pointers.

Definition at line 93 of file Linkage.hh.

Head ProtoThread::runq
staticprotected

Definition at line 180 of file ProtoThread.hh.

The documentation for this class was generated from the following files: