Thread.h

Go to the documentation of this file.

/** @file Thread.h
* @author Gabor Madl
* @date Created 02/2005
* @brief Thread implementation.
*
*
* =================================================================
* DREAM License v2.0
* 
* DREAM - Distributed Real-time Embedded Analysis Method
* http://dre.sourceforge.net.
* Copyright (c) 2005-2007 Gabor Madl, All Rights Reserved.
* 
* This file is part of DREAM.
* 
* DREAM is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation. No future versions of
* the GPL license may be automatically applied to DREAM. It is in
* the sole discretion of the copyright holder to determine whether
* DREAM may be released under a different license or terms. There
* are no restrictions on the use of DREAM for any purpose.
* 
* DREAM is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* 
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
* MA 02110-1301, USA.
* 
* By submitting comments, suggestions, code, code snippets,
* techniques (including that of usage), and algorithms, submitters
* acknowledge that they have the right to do so, that any such
* submissions are given freely and unreservedly, and that they
* waive any claims to copyright or ownership. In addition,
* submitters acknowledge that any such submission might become
* part of the copyright maintained on the overall body of code,
* which comprises DREAM. By making a submission, submitter agrees
* to these terms. Furthermore, submitters acknowledge that the
* incorporation or modification of such submissions is entirely
* at the discretion of the moderators of the DREAM project.
* 
* DREAM links to the Libxml2 third party library. Please see 
* COPYING-libxml for the copyright information of Libxml2.
* =================================================================
*/

#ifndef DREAM_THREAD
#define DREAM_THREAD

#include <iostream>
#include <map>
#include <algorithm>

namespace DREAM
{
        class NodeList;
        class Thread;
        class Channel;
}

#include "Task.h"
#include "Scheduler.h"
#include "Exception.h"

namespace DREAM
{

/** This is a simple map to store Nodes.
* It is the base class for Thread that implements priority-based scheduling.
*/
class NodeList
{
public:
        /** iterator class for convenience. */
//      typedef typename Iterator<> iterator;

        /** const_iterator class for convenience. */
//      typedef typename Const_Iterator<> const_iterator;

        /** Allow iterators to manipulate protected members. */
//      friend class iterator;

        /** Allow iterators to manipulate protected members. */
//      friend class const_iterator;

        /**Constructor. */
        NodeList ();

        /**Destructor. */
        virtual ~NodeList ();

        /** Adds a new Node to the list 
        * @param node_ptr specifies the Node to be added.
        */
        virtual void add (DREAM::Node* node_ptr);

        /** Clears contents of the map. */
        virtual void clear ();

        /** Does nothing. A nonconcurrent thread does not have an execution queue. */
        virtual void dequeue (DREAM::Node* node_ptr)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        {};

        /** Does nothing. A nonconcurrent thread does not have an execution queue. */
        virtual void enqueue (DREAM::Node* node_ptr) {};

        /** Returns a Node from the list.
        * @param id specifies the id of the Node to be returned.
        * @return pointer to the Node.
        */
        virtual DREAM::Node* find (const std::string& id) const;

        /** Returns the whole node_map_ for manipulation.
        * @return pointer to the node_map_.
        */
        virtual DREAM::NODE_MAP* get_map ()
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** Publisher.
        * Calls the Node::publish () function of all the Nodes in the map.
        */
        virtual void publish () const;

        /** Removes a Node from the list.
        * @param id specifies the Node to be removed.
        */
        virtual void erase (const std::string& id)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** Takes transitions for every Node in the NodeList. */
        virtual void take_transitions ()
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

protected:
        /** Map to store Nodes */
        DREAM::NODE_MAP node_map_;
};

/** A Thread is a map of schedulable Nodes.
* The Scheduler manages the execution of Threads based on their priority and the scheduling policiy.
*/
class Thread : public DREAM::NodeList
{
public:
        /**Constructor. */
        Thread (DREAM::Scheduler* scheduler_ptr, uint priority = 0, uint threads = 1);

        /**Destructor. */
        virtual ~Thread ();

        /** Adds a Task in the error AVL tree - error_avltree_.
        * @param task_ptr is a pointer to the Task which will be put in the error AVL tree - error_avltree_.
        */
        virtual void add_error (DREAM::Task* task_ptr);

        /** Returns the number of available Threads. */
        virtual uint availablethreads () const;

        /** Deploys a Thread to a Scheduler.
        * This function updates the scheduler_ptr in the Thread.
        * @param scheduler_ptr is the Scheduler where the Thread will be deployed.
        */
        virtual void deploy (DREAM::Scheduler* scheduler_ptr)
                throw (DREAM::Exception);

        /** Removes an idle Node from the execution queue - exec_map_.
        * @param node_ptr is a pointer to the Node which will be removed from the execution queue - exec_map_.
        */
        virtual void dequeue (DREAM::Node* node_ptr)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

#ifdef DREAM_RACE_CONDITION
        /** Puts an enabled Channel in the execution queue - exec_map_ - and reschedules if necessary.
        * @param channel_ptr is a pointer to the Channel which will be put in the execution queue - exec_map_.
        */
        virtual void enqueue (DREAM::Channel* channel_ptr);

        /** Puts an enabled Task in the execution queue - exec_map_ -, and the recent queue - recent_map_ - and reschedules if necessary.
        * @param task_ptr is a pointer to the Task which will be put in the queues.
        */
        virtual void enqueue (DREAM::Task* task_ptr);
#else
        /** Puts an enabled Node in the execution queue - exec_map_ -, and the recent queue - recent_map_ - and reschedules if necessary.
        * @param node_ptr is a pointer to the Node which will be put in the queues.
        */
        virtual void enqueue (DREAM::Node* node_ptr);
#endif

        /** Frees an available Thread from the lane. */
        virtual void freethread ()
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** Returns the whole exec_map_ for manipulation.
        * @return a pointer to the exec_map_.
        */
        virtual DREAM::NODE_MAP* get_exec_map ()
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

#ifdef DREAM_RACE_CONDITION
        /** Returns whether a Task has been recently enabled */
        virtual const DREAM::TASK_AVLTREE* get_recent_avltree () const;
#endif

        /** Return the time of the next event generated by the Thread. */
        virtual double next_event () const
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** Returns the priority of the Thread.
        * @return the priority of the Thread priority_.
        */
        virtual uint priority () const;

#ifdef DREAM_RACE_CONDITION
        /** Returns whether a Task has been recently enabled together with other tasks.
        * @param task_ptr is a pointer to the Task to be checked.
        */
        virtual bool recent (DREAM::Task* task_ptr) const;
#endif

        /** Resets Nodes in the map */
        void reset ()
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** Checks whether the Thread is schedulable.
        * @return true is the Thread is schedulable, false otherwise.
        */
        virtual bool schedulable () const;

        /** Returns a pointer to the Scheduler.
        * Used in output generation.
        */
        virtual const DREAM::Scheduler* scheduler () const
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;
        
        /** Returns a pointer to the Scheduler.
        * Used in output generation.
        */
        virtual DREAM::Scheduler* scheduler ()
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;
        
        /** Returns the number of the Threads. */
        virtual uint threads () const;

        /** Time jump.
        * @param time_step specifies the time step to be made.
        */
        virtual void time_step (double time_step)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** Function used to output info.
        * @param output is the std::string to be displayed.
        */
        virtual void trace (const std::string& output) const;

        /** Takes an available Thread from the lane. */
        virtual void usethread ()
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** This function is part of the IF system description generator.
        * @param task_map stores the Task pointers.
        * @param channel_map stores the Channel pointers.
        * @param timer_map stores the Timer pointers.
        * @param f_stream is the output stream to be written to.
        */
        virtual void visitor_if (DREAM::NODE_MAP* task_map, DREAM::NODE_MAP* channel_map, DREAM::NODE_MAP* timer_map, std::ofstream& f_stream)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** This function fills the IDs (names) of tasks, channels and timers to the parameter lists.
        * The function is used to generate output for model checkers.
        * @param task_map stores the Task pointers.
        * @param channel_map stores the Channel pointers.
        * @param timer_map stores the Timer pointers.
        */
        virtual void visitor_map (DREAM::NODE_MAP* task_map, DREAM::NODE_MAP* channel_map, 
                DREAM::NODE_MAP* timer_map)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                        throw (DREAM::Exception)
#endif
        ;

        /** This function builds the task list for manipulation.
        * The function is used by genetic algorithms.
        * @param task_avltree stores the Task pointers.
        */
        virtual void visitor_task_avltree (DREAM::TASK_AVLTREE* task_avltree)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** This function updates task values in the system.
        * The function is used by genetic algorithms.
        * @param task_avltree stores the Task pointers.
        */
        virtual void visitor_update_task_avltree (DREAM::TASK_AVLTREE* task_avltree)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                throw (DREAM::Exception)
#endif
        ;

        /** This function is part of the Uppaal system description generator.
        * @param task_map stores the Task pointers.
        * @param channel_map stores the Channel pointers.
        * @param timer_map stores the Timer pointers.
        * @param f_stream is the output stream to be written to.
        */
        virtual void visitor_uppaal (DREAM::NODE_MAP* task_map, DREAM::NODE_MAP* channel_map, 
                DREAM::NODE_MAP* timer_map, std::ofstream& f_stream)
#ifdef DREAM_ENHANCED_EXCEPTION_CHECKING
                        throw (DREAM::Exception)
#endif
        ;

private:

        /** Specifies the number of available threads in the lane. */
        uint availablethreads_;

        /** Map to store Nodes. */
        DREAM::NODE_MAP exec_map_;

#ifdef DREAM_RACE_CONDITION
        /** AVL tree that stores Nodes that have just become enabled.
        * This AVL tree is used by the model checker to check for race conditions.
        */
        DREAM::TASK_AVLTREE recent_avltree_;
#endif

        /** Priority of the Thread. */
        uint priority_;

        /** Pointer to the Scheduler which manages the NodeList/Thread. */
        DREAM::Scheduler* scheduler_ptr_;

        /** Specifies the number of threads in the lane. */
        uint threads_;
};

}

#endif

---