dsched.h

a useful spiking neural networks simulator

/** 
 * @file  dsched.h
 * @brief Distributed scheduler
 *
 * @author Makino, Takaki <[e-mail]>
 * @date 2003-05-01
 * @version $Id: dsched.h,v 1.2 2003/05/08 07:24:56 t Exp $
 *
 * Copyright (C) 2003 Makino, Takaki.  All rights reserved.
 */

#ifndef __dsched_h
#define __dsched_h

#include <math.h>

#include <functional>
#include <map>
#include <set>
#include <vector>
#include <queue>
#include <string>

#include "punnets_base.h"

/////////////////////////////////////////////////////////////////////////
namespace punnets_common {
/////////////////////////////////////////////////////////////////////////

class tsched_double;
typedef tsched_double tscheduler;

class tevent;
class greater_tevent;
typedef std::priority_queue< tevent, std::vector<tevent>, greater_tevent > tqueue;

/// \addtogroup Scheduling
/// @{

/** Action (some affection to an entity)
 *  
 *  Class taction is a abstract base class of "changing something", such as pulse arrival etc.
 *  Event is an instance of an action, represented by a pair of time and action.
 *  When simulation time reaches the event time, the scheduler triggers the event; the corresponding action is
 *  "activated" to perform the change.  
 *  E.g. when a pulse arrival is activated, the potential of the destination neuron is changed.
 *
 *  Punnets adopts a distributed queue model, in which every action has a corresponding 
 * "local queue". \todo write more
 */

class taction
{
public:
	taction() { }
	virtual ~taction() { }
	
	/// Activates the action at the specified time.  When the correspinding 
	/// new events are generated by the action, it is scheduled to the scheduler.
	virtual void activate(tscheduler &scheduler, ntime_t current_time) = 0;
	/// Obtain a local event queue of this action. 
	virtual tqueue *queue() const = 0;
	/// Get the class name of this action.  Primarily for debugging.
	virtual const char *getClassName() const = 0;
};

/**  Event (scheduled action)
 *  
 *  Class tevent represents a scheduled event, which is a pair of a scheduled time and an action.
 *  When simulation time reaches the event time, the scheduler triggers the event; the corresponding action is
 *  "activated" to perform the change.
 */

class tevent
{
	ntime_t time;
	taction *act;

public:
	/// construct an event with the specified time and action.
	tevent(ntime_t itime, taction &iact)
		: time(itime), act(&iact) { /*act->getName();*/ }

	/// Obtain the time component of the event.
	ntime_t getTime() const { return time; }
	/// Obtain the action component of the event.
	taction& getAction() const { return *act; }
	
	/// When the event time reaches, scheduler calls this member to trigger the event.
	void activate(tscheduler &scheduler) const 
		{ act->activate(scheduler, time); }
};


////////////////////////////////////////////////////////////////////////
/// Function class to compare event times
///
/// This class is used to construct a local priority queue on STL.  In a queue, 
/// events are sorted in an ascending order of event time.
/// This class is privately used internally in the punnets library. 

struct greater_tevent 
	: public std::binary_function<const tevent &, const tevent &, bool>
{
	bool operator() (const tevent &a, const tevent &b) 
		{ return a.getTime() > b.getTime(); }
};


////////////////////////////////////////////////////////////////////////
/// Event scheduler class.
/// 
/// The scheduler class activates events in an order of time.

class tsched_double
{
	/// An entry of global priority queue. 
	typedef std::pair< ntime_t, tqueue * > sched_entry;
	
	/// This class is used to construct a global priority queue on STL.  
	struct less_sched_entry 
		: public std::binary_function< const sched_entry &, const sched_entry &, bool >
	{
		bool operator() (const sched_entry &a, const sched_entry &b) 
		{ return (a.first != b.first ? a.first < b.first : a.second < b.second); }
	};

	/// The global queue, in which local queues are sorted.
	std::set< sched_entry, less_sched_entry > global_queue;
	/// ???
	const tqueue * processing_queue;

public:
	/// Constructs a scheduler with no events.
	tsched_double();

	/// Schedule an event.
	void scheduleEvent(const tevent &event);
	/// Schedule an action for the specified time.
	void scheduleEvent(ntime_t t, taction &act) 
			{ scheduleEvent( tevent(t, act) ); }
	/// Tests if the scheduler is not empty.
	bool isScheduled() const { return ! global_queue.empty(); }
	/// Run the simulation (continue triggering events) until the specified time.
	ntime_t run(ntime_t until = HUGE_VAL);
};

/// @}
/////////////////////////////////////////////////////////////////////////
} // namespace punnets_common
/////////////////////////////////////////////////////////////////////////

#endif // __dsched_h