rtos.h

//***************************************************************************
//
// file : bmptk/core/rtos.h
//
// LICENSE (MIT expat license, copy of bmptk/license.txt)
//
// Copyright (c) 2012 
//   Wouter van Ooijen (wouter@voti.nl)
//   Marten Wensink
// 
// Permission is hereby granted, free of charge, to any person obtaining
// a copy of this software and associated documentation files (the
// "Software"), to deal in the Software without restriction, including
// without limitation the rights to use, copy, modify, merge, publish,
// distribute, sublicense, and/or sell copies of the Software, and to
// permit persons to whom the Software is furnished to do so, subject to
// the following conditions:
// 
// The above copyright notice and this permission notice shall be included
// in all copies or substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE..
//
//***************************************************************************

#include <iostream>
#include <limits>

namespace bmptk {

namespace rtos {

#define global_logging 0

#define BMPTK_RTOS_STATISTICS_ENABLED 1

const unsigned int BMPTK_RTOS_DEFAULT_STACK_SIZE = 2048;

const unsigned int BMPTK_RTOS_MAX_PRIORITY = 10000;

// the macro BMPTK_RTOS_STATISTICS is used to prefix a single line
// that will be commented out when statistics is disabled
#if BMPTK_RTOS_STATISTICS_ENABLED
   #define BMPTK_RTOS_STATISTICS( x ) x
#else
   #define BMPTK_RTOS_STATISTICS( x )
#endif

class task;
class event;
class waitable;
class flag;
class timer;
class clock;
class mutex;
template <class T> class mailbox;
template <class T, const int SIZE> class channel;
template <class T> class pool;
class mailbox_base;
class channel_base;
class pool_base;
class waitable_set;
class callback;


//************************************************************************
//
// some supporting stuff
//
//************************************************************************

//
void run();

//
task * current_task();

void print( std::ostream & stream );

//
void statistics_clear();

void display_statistics();


//************************************************************************
//
// class event
//
//
//
//************************************************************************

class event {
public:
   
   void print( std::ostream & s, bool header ) const;
        
   bool operator==( const event & rhs ) const;
   
   bool operator==( const waitable & rhs ) const;
   
   bool operator!=( const event & rhs ) const {
      return ! ( *this == rhs );
   }
   
   bool operator!=( const waitable & rhs ) const {
      return ! ( *this == rhs );
   }
   
   //
   event operator+( const event & rhs ) const;

private:
   
   task * t;
   
   //
   unsigned int mask;
   
   event( task * t, unsigned int mask ): t( t ), mask( mask ){}

   friend class waitable_set;
   friend class waitable;
   friend class channel_base;
   friend void beat();
   friend class flag;
   friend class callback;
   friend class clock;
   friend class timer;
};


//************************************************************************
//
// class waitable
//
//
//
//************************************************************************

class waitable : public event {
public:

   //
   virtual void clear();

protected:
   
   //
   waitable( task * task , const char *name );
   
   void set();

   BMPTK_RTOS_STATISTICS( const char *waitable_name; )

   friend class waitable_set;
};


//************************************************************************
//
// class flag
//
//
//
//************************************************************************

class flag : public waitable {
public:
   
   //
   flag( task * t, const char *name = "" );
   
   //
   void set ();
   
   void print( std::ostream & s, bool header = true ) const;

private:
   
     // this information is needed for statistics only
   BMPTK_RTOS_STATISTICS( flag *next_flag; )
   BMPTK_RTOS_STATISTICS( unsigned int n_sets; )
   BMPTK_RTOS_STATISTICS( unsigned int n_gets; )
   
   friend class event;
   friend class waitable_set;
   friend void add( flag * f );
   friend void print( std::ostream & stream );
};


//************************************************************************
//
// class waitable_set
//
// This is an private implementation construct, it is not documented
//
//************************************************************************

#ifndef DOXYDOC

class waitable_set {
private:
   event wait( unsigned int mask );

public:
   task * client;
   unsigned int current_waitables;
   unsigned int requested_waitables;
   unsigned int used;

   waitable_set( task * client ):
      client( client ),
      current_waitables( 0 ),
      requested_waitables( 0 ),
      used( 0 ) {}

   unsigned int waitable_allocate();
   void set( const waitable &w );
   void clear( const waitable &w );

   event wait(){ return wait( ~0 ); }
   event wait( const waitable & w ){ 
      return wait( w.mask ); 
   }
   event wait( const event & set ){ 
      return wait( set.mask );
   }
};

#endif


//************************************************************************
//
// class task
//
//
//
//************************************************************************

class task {

private:

      // The rtos uses block() and unblock() to implement the
      // synhronisation mechanisms (waitables).
   bool task_is_blocked;

      // a lower number means a higher priority, 0 is highest
   unsigned int task_priority;

      // timer for sleep() call
   timer * sleep_timer;
   
   friend void task_trampoline();   
   friend void sleep_until( time t );
   
protected:

      // task name, only for statistics
   BMPTK_RTOS_STATISTICS( const char *task_name; )

   //
   virtual void main() = 0;
   
public:

   //
   task(
      unsigned int priority  = BMPTK_RTOS_MAX_PRIORITY,
      const char * tname     = "",
      unsigned int stacksize = BMPTK_RTOS_DEFAULT_STACK_SIZE
   );

   virtual ~task () {
      fatal_error_detected( "task destructor called" ); 
   }

   //
   void release();

   unsigned int priority() const {
      return task_priority; 
   }
   
   const char * name() const {
      #if BMPTK_RTOS_STATISTICS_ENABLED
         return task_name; 
      #else
         return "";
      #endif
   }   
      
   bool is_ready() const {
      return ! task_is_blocked;
   }
   bool is_blocked() const {
      return task_is_blocked;
   }

   void print( std::ostream & stream, bool header = true ) const;
               
   //
   event wait(){ return waitables.wait(); }
   
   //
   event wait( const waitable & w ){ 
      return waitables.wait( w ); 
   }
   
   //
   event wait( const event & set ){ 
      return waitables.wait( set ); 
   }

   void set( flag &w ){ 
      w.set(); 
   }

   //
   void ignore_activation_time(){
      ignore_this_activation = true;
   }

private:

   void statistics_clear(){
      runtime_max = 0 * ms;
      activations = 0;
   }

   waitable_set waitables;

   void block();

   void unblock();

   int activated;
   time latency_max;
   time runtime_max;
   int activations;
   bool ignore_this_activation;

   task * nextTask;

   task * next_mutex_waiter;

   bmptk::context *context;

   friend class periodic_task;
   friend class waitable_set;
   friend class flag;
   friend class waitable;
   friend class mutex;
   friend void print( std::ostream & stream );
   friend void do_statistics_clear();
   friend void add( task * new_task );
   friend void beat();
   // friend void channel_base::print( std::ostream & stream, bool header ) const;
};


//************************************************************************
//
// class callback
//
// rtos private implementation class
//
//************************************************************************

#ifndef DOXYDOC

class callback : public waitable {
public:

   callback( task *t, const char *name );

   // a callback should never be destroyed
   virtual ~callback() {
      fatal_error_detected( "callback destructor called" );
   }

   // the time_up function must be provided by a derived class
   virtual void time_up( void ) = 0;
   
   void print( std::ostream & s, bool header = true ) const;   

protected:

   // the callback must be called at t
   void await( time t ){ 
      deadline = t;
      running = true;
   }

   // the callback must fire <time> from now
   void start( time t ){ 
      await( bmptk::current_time() + t );
   }
   
   // the callback must fire in the future, at a multiple of 
   // <time> from the last firing
   void restart( time t ){
      time now = bmptk::current_time();
      while( deadline <= now ){ 
         deadline += t; 
      }
      running = true;
   }

   // abort a started timer
   virtual void cancel(){ 
      running = false;
   }

   // true iff the timer is running
   bool running;
   
   // the moment the callback should be called
   time deadline;

   // for the rtos to link timers in a chain
   callback * next_callback;

   friend class task;
   friend void beat();
   friend void add( callback * t );
   friend void handle_callbacks( time t );
};

#endif


//************************************************************************
//
// class timer
//
//
//
//************************************************************************

class timer : public callback {
public:
   
   timer( task * t, const char *name = "" );
   
   //
   void set( time t );
   
   //
   void await( time t );
    
   //
   void cancel();

   void print( std::ostream & s, bool header = true ) const;

private:

   void time_up();
   BMPTK_RTOS_STATISTICS( timer *next_timer; )
   BMPTK_RTOS_STATISTICS( unsigned int n_sets; )
   BMPTK_RTOS_STATISTICS( unsigned int n_cancels; )
   
   friend void add( timer * t );
   friend void print( std::ostream & stream );
   friend void beat();
};

//************************************************************************
//
// class clock
//
//
//
//************************************************************************

class clock :  public callback {
public:
   
   //
   clock( 
      task * t, 
      time interval, 
      const char *name = "" 
   );
   
   //
   void clear(){ waitable::clear(); }
      
   time interval(){ 
      return _interval; 
   }

   void print( std::ostream & s, bool header = true ) const;

private:
   void time_up();
   time _interval;
   BMPTK_RTOS_STATISTICS( clock *next_clock; )
   BMPTK_RTOS_STATISTICS( unsigned int ticks; )
   
   friend void add( clock * c );
   friend void beat();
   friend void print( std::ostream & stream );
};


//************************************************************************
//
// class pool_base
//
//
//************************************************************************

#ifndef DOXYDOC

class pool_base {
public:

   pool_base( const char * name );
   ~pool_base() {
      fatal_error_detected( "pool destructor called" );
   }
   void print( std::ostream & s, bool header = true ) const;

#if BMPTK_RTOS_STATISTICS_ENABLED
   unsigned int reads;
   unsigned int writes;
   pool_base * next_pool;
   const char * pool_name;
#endif

};

#endif


//************************************************************************
//
// class pool
//
//
//
//************************************************************************

template <class T> class pool : public pool_base {
public:
   
   //
   pool( const char *name = "" ): pool_base( name ){}

   //
   void write (T item) {
      BMPTK_RTOS_STATISTICS( reads++; )
      data = item;
   }

   //
   T read (void) {
      BMPTK_RTOS_STATISTICS( writes++; )
      return data;
   }

private:
   T data;
};


//************************************************************************
//
// class mutex
//
//
//
//************************************************************************

class mutex {
public:
   
   //
   mutex( const char *name = "" );
   
   //
   ~mutex();  
   
   void print( std::ostream & stream, bool header = true ) const;

   void wait   (void);
   
   //
   void signal (void);

private:

   task * owner;             // current owner of the mutex
   task * waiters;           // head of the waiting tasks queue

#if BMPTK_RTOS_STATISTICS_ENABLED
   const char * mutex_name;  // for logging
   mutex *next_mutex;        // queue of all mutexes, for logging
   int wait_count;           // counts # wait calls;
#endif

   friend void add( mutex * m );
   friend void print( std::ostream & stream );
};


//************************************************************************
//
// class mailbox_base
//
// rtos private implementation class
//
//************************************************************************

#ifndef DOXYDOC

class mailbox_base {
public:
   mailbox_base( const char *name );

   ~mailbox_base() {
      fatal_error_detected( "mailbox destructor called" );
   }

   void print( std::ostream & s, bool header = true ) const;

   task * client;
#if BMPTK_RTOS_STATISTICS_ENABLED
   const char * mailbox_name;
   unsigned int writes;
   mailbox_base *next_mailbox;
#endif

};

#endif

//************************************************************************
//
// class mailbox
//
//
//
//************************************************************************

template <class T> class mailbox : mailbox_base {
public:
   
   //
   mailbox( const char *name = ""  ): mailbox_base( name ){}

   //
   void write( const T item ) {
      BMPTK_RTOS_STATISTICS( writes++; )
      data = item;
      if ( client != 0 ) {
            // someone is waiting to read, unblock it
            client->unblock();
         } else {
             // block until the reader gets the data
             client = bmptk::rtos::current_task();
             client->block();
         }
   }
   
   //
   T read (void) {
      if ( client == 0 ) {
         // no writer yet, so wait for a writer
         client = bmptk::rtos::current_task();
         client->block();
      }
      else {
         // unblock the writer
         // but first make sure the client is 0 !
         task *temp = client;
         client = 0;
         temp->unblock();
      }
      return data;
   }

private:
   T data;
};

//************************************************************************
//
// class channel_base
//
// rtos private implementation class
//
//************************************************************************

#ifndef DOXYDOC

class channel_base : public waitable{
public:
   virtual ~channel_base() {
      fatal_error_detected( "channel destructor called" );
   }

   void print( std::ostream & s, bool header = true ) const;

protected:
public:

   channel_base( task * t, const char *name );

#if BMPTK_RTOS_STATISTICS_ENABLED
   const char *channel_name;
   channel_base *next_channel;
   int writes;
   int ignores;
#endif

   int qSize;
   int head;
   int tail;
};

#endif

//************************************************************************
//
// class channel
//
//
//
//************************************************************************

template <class T, const int SIZE> class channel : public channel_base {
public:

   //
   channel( task * t, const char *name = "" ): channel_base( t, name ){}

   void write( T item ) {
      if( qSize < SIZE ) {
         BMPTK_RTOS_STATISTICS( writes++; )
         queue[head] = item;
         if( ++head == SIZE ) {
            head = 0;
         }
         qSize += 1;
         waitable::set();
      } else {
         BMPTK_RTOS_STATISTICS( ignores++; )
      }
   }

   T read() {
      if( qSize == 0 ) {
         t->wait( *this );
      }

      if( qSize == 0 ) {
         fatal_error_detected( "channel should not be empty now");
      }
      T buf = queue[ tail ];
      if( ++tail == SIZE ) {
         tail = 0;
      }
      qSize -= 1;
      if( qSize > 0 ) {
         waitable::set();
      } else {
         waitable::clear();
      }
      return buf;
   }

   void clear (void) {
      qSize = 0;
      head = tail = 0;
      waitable::clear();
   }
   
private:
   T queue[ SIZE] ;
};


std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::task & t );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::flag & f );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::event & e );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::callback & c );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::timer & t );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::clock & c );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::channel_base & c );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::mutex & m );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::mailbox_base & m );

std::ostream & operator<< ( std::ostream & s, const bmptk::rtos::pool_base & p );



}; // namespace rtos;

}; // namespace bmptk;