freedm::broker::CBroker Class Reference

Scheduler for the DGI modules.

#include <CBroker.hpp>

Inheritance diagram for freedm::broker::CBroker:

Public Types
typedef boost::function< void()>	BoundScheduleable
typedef std::string	ModuleIdent
typedef std::vector< PhaseTuple >	ModuleVector
typedef std::map< TimerHandle, bool >	NextTimeMap
typedef unsigned int	PhaseMarker
typedef std::pair< ModuleIdent, boost::posix_time::time_duration >	PhaseTuple
typedef std::map< ModuleIdent, std::list< BoundScheduleable > >	ReadyMap
typedef boost::function< void(boost::system::error_code)>	Scheduleable
typedef std::map< TimerHandle, ModuleIdent >	TimerAlloc
typedef unsigned int	TimerHandle
typedef std::map< TimerHandle, boost::asio::deadline_timer * >	TimersMap

Public Member Functions
	~CBroker ()
	De-allocates the timers when the CBroker is destroyed. More...
TimerHandle	AllocateTimer (ModuleIdent module)
	Allocate a timer to a specified module. More...
CClockSynchronizer &	GetClockSynchronizer ()
	Returns the synchronizer. More...
boost::asio::io_service &	GetIOService ()
	Return a reference to the boost::ioservice. More...
void	HandleSignal (const boost::system::error_code &error, int parameter)
	Handle signals from the operating system (ie, Control-C) More...
void	HandleStop (unsigned int signum=0)
	Handles the stop signal from the operating System. More...
bool	IsModuleRegistered (ModuleIdent m)
	Checks to see if a module is registered with the scheduler. More...
void	RegisterModule (ModuleIdent m, boost::posix_time::time_duration phase)
	Registers a module for the scheduler. More...
void	Run ()
	Starts the DGI Broker scheduler. More...
int	Schedule (TimerHandle h, boost::posix_time::time_duration wait, Scheduleable x)
	Schedules a task that will run after a timer expires. More...
int	Schedule (ModuleIdent m, BoundScheduleable x, bool start_worker=true)
	Schedule a task to be run as soon as the module is active. More...
void	Stop (unsigned int signum=0)
	Requests that the Broker stops execution to exit the DGI. More...
boost::posix_time::time_duration	TimeRemaining ()
	Returns how much time the current module has left in its phase. More...

Static Public Member Functions
static CBroker &	Instance ()
	Get the singleton instance of this class. More...

Private Member Functions
	CBroker ()
	Private constructor for the singleton instance. More...
void	ChangePhase (const boost::system::error_code &err)
	An task that will advance the Broker's active module to the next module. More...
void	ScheduledTask (Scheduleable x, TimerHandle handle, const boost::system::error_code &err)
	Adds a task scheduled by a module to the task queue when the timer expires. More...
void	Worker ()
	Executes tasks from the active module's task queue. More...

Private Attributes
TimerAlloc	m_allocs
	Timer allocations for modules. More...
bool	m_busy
	True while the worker is actively running tasks. More...
TimerHandle	m_handlercounter
	The current counter for the time handlers. More...
boost::asio::io_service	m_ioService
	The io_service used to perform asynchronous operations. More...
boost::posix_time::ptime	m_last_alignment
	The last time the phases were aligned. More...
ModuleVector	m_modules
	List of modules for the scheduler. More...
NextTimeMap	m_nexttime
	Maps handle to bool: if a timer handle is set to expire for the next round. More...
NextTimeMap	m_ntexpired
	Maps if a specific timer has been cancelled or triggered by end of round. More...
PhaseMarker	m_phase
	The active module in the scheduler. More...
boost::posix_time::ptime	m_phaseends
	Computed ptime for when the current phase ends. More...
boost::asio::deadline_timer	m_phasetimer
	Timer for the phases. More...
ReadyMap	m_ready
	A map of jobs that are ready to run as soon as their phase comes up. More...
boost::mutex	m_schmutex
	Lock for the scheduler. More...
boost::asio::signal_set	m_signals
	The registered signal handlers. More...
bool	m_stopping
	Flag to prevent modules from scheduling, set when the DGI is stopping. More...
boost::mutex	m_stoppingMutex
	Lock for m_stopping. More...
boost::shared_ptr< CClockSynchronizer >	m_synchronizer
	The clock synchronizer which aligns clocks between DGIs. More...
TimersMap	m_timers
	A relation between the timer handles and the actual timer objects. More...

Member Typedef Documentation

typedef boost::function<void ()> freedm::broker::CBroker::BoundScheduleable

typedef std::string freedm::broker::CBroker::ModuleIdent

typedef std::vector< PhaseTuple > freedm::broker::CBroker::ModuleVector

typedef std::map<TimerHandle, bool > freedm::broker::CBroker::NextTimeMap

typedef unsigned int freedm::broker::CBroker::PhaseMarker

typedef std::pair<ModuleIdent, boost::posix_time::time_duration> freedm::broker::CBroker::PhaseTuple

typedef std::map<ModuleIdent, std::list< BoundScheduleable > > freedm::broker::CBroker::ReadyMap

typedef boost::function<void (boost::system::error_code)> freedm::broker::CBroker::Scheduleable

typedef std::map<TimerHandle, ModuleIdent> freedm::broker::CBroker::TimerAlloc

typedef unsigned int freedm::broker::CBroker::TimerHandle

typedef std::map<TimerHandle, boost::asio::deadline_timer* > freedm::broker::CBroker::TimersMap

Constructor & Destructor Documentation

freedm::broker::CBroker::~CBroker

(

)

Description:

Cleans up all the timers from this module since the timers are stored as pointers.

Precondition:

None

Postcondition:

All the timers are destroyed and their handles no longer point at valid resources.

freedm::broker::CBroker::CBroker ( )

private

Private constructor for the singleton Broker instance.

Member Function Documentation

CBroker::TimerHandle freedm::broker::CBroker::AllocateTimer

(

CBroker::ModuleIdent

module

)

Description:

Returns a handle to a timer to use for scheduling tasks. Timer handles are used in Schedule() calls.

Precondition:

The module is registered

Postcondition:

A handle to a timer is returned.

Parameters

module

the module the timer should be allocated to

Returns

A CBroker::TimerHandle that can be used to schedule tasks.

void freedm::broker::CBroker::ChangePhase ( const boost::system::error_code &  err )

private

Description:

Changes the current active module when time allotted to the module has passed.

Precondition:

This function was scheduled to be called when the time allotted to the current active modules has passed

Postcondition:

The phase has been changed to the new active module. If the worker was not already running, it is started to run tasks for the new active module.

CClockSynchronizer & freedm::broker::CBroker::GetClockSynchronizer

(

)

Description:

Returns a reference to the ClockSynchronizer object.

Precondition:

None

Postcondition:

Any changes to the ClockSynchronizer will affect the object owned by the broker.

Returns

A reference to the Broker's ClockSynchronizer object.

boost::asio::io_service & freedm::broker::CBroker::GetIOService

(

)

Description:

returns a refernce to the ioservice used by the broker.

Returns

The ioservice used by this broker.

void freedm::broker::CBroker::HandleSignal	(	const boost::system::error_code &	error,
		int	signum
	)

Description:

Handle signals that terminate the program.

Precondition:

None

Postcondition:

The broker is scheduled to be stopped.

void freedm::broker::CBroker::HandleStop

(

unsigned int

signum = 0

)

Description:

Handles closing all the sockets connection managers and Services. Should probably only be called by CBroker::Stop().

Parameters

signum

positive if called from a signal handler, or 0 otherwise

Precondition:

The ioservice is running but all agents have been stopped.

Postcondition:

The Broker has been cleanly shut down.

Postcondition:

The devices subsystem has been cleanly shut down.

CBroker & freedm::broker::CBroker::Instance ( )

static

Access the singleton Broker instance.

bool freedm::broker::CBroker::IsModuleRegistered

(

ModuleIdent

m

)

Description:

Checks to see if a module is registered with the scheduler.

Precondition:

None

Postcondition:

None

Parameters

m	the identifier for the module.

Returns

true if the module is registered with the broker.

void freedm::broker::CBroker::RegisterModule	(	CBroker::ModuleIdent	m,
		boost::posix_time::time_duration	phase
	)

Description:

Places the module in to the list of schedulable phases. The scheduler cycles through registered modules to do real-time round robin scheduling.

Precondition:

None

Postcondition:

The module is registered with a phase duration specified by the phase parameter.

Parameters

m	the identifier for the module.
phase	the duration of the phase.

void freedm::broker::CBroker::Run

(

)

Description:

Starts the adapter factory. Runs the ioservice until it is out of work. Runs the clock synchronizer.

Precondition:

The ioservice has some schedule of jobs waiting to be performed (so it doesn't exit immediately).

Postcondition:

The ioservice has stopped.

Error Handling:

Could raise arbitrary exceptions from anywhere in the DGI.

int freedm::broker::CBroker::Schedule	(	CBroker::TimerHandle	h,
		boost::posix_time::time_duration	wait,
		CBroker::Scheduleable	x
	)

Description:

Given a scheduleable task that should be run in the future. The task will be scheduled to run by the Broker after the timer expires and during the module that owns the timer's phase. The attempt to schedule may be rejected if the Broker is stopping, indicated by the return value.

Parameters

h	The handle to the timer being set.
wait	the amount of the time to wait. If this value is "not_a_date_time" The wait is converted to positive infinity and the time will expire as soon as it is not the module that owns the timer's phase.
x	A schedulable, a functor, that expects a single boost::system::error_code parameter and returns void, created via boost::bind()

Precondition:

The module is registered

Postcondition:

If the Broker is not stopping, the function is scheduled to be called in the future. If a next time function is scheduled, its timer will expire as soon as its round ends. If the Broker is stopping the task will not be scheduled.

Returns

0 on success, -1 if rejected

int freedm::broker::CBroker::Schedule	(	ModuleIdent	m,
		BoundScheduleable	x,
		bool	start_worker = true
	)

Description:

Given a module and a task, put that task into that modules job queue. The attempt to schedule will be rejected if the Broker is stopping.

Precondition:

The module is registered.

Postcondition:

The task is placed in the work queue for the module m. If the start_worker parameter is set to true, the module's worker will be activated if it isn't already.

Parameters

m	The module the schedulable should be run as.
x	The method that will be run. A functor that expects no parameters and returns void. Created via boost::bind()
start_worker	tells the worker to begin processing again, if it is currently idle. The worker may be idle if the work queue is currently empty

Returns

0 on success, -1 if rejected because the Broker is stopping.

void freedm::broker::CBroker::ScheduledTask ( CBroker::Scheduleable  x, CBroker::TimerHandle  handle, const boost::system::error_code &  err  )

private

Description:

When a timer for a task expires, this function is called to insert the readied task into owning module's ready task queue.

Precondition:

A task is scheduled for execution

Postcondition:

The task is entered into th ready queue.

void freedm::broker::CBroker::Stop

(

unsigned int

signum = 0

)

Description:

Registers a stop command into the io_service's job queue. when scheduled, the stop operation will terminate all running modules and cause the ioservice.run() call to exit.

Precondition:

The ioservice is running and processing tasks.

Postcondition:

The command to stop the ioservice has been placed in the service's task queue.

Parameters

signum

A signal identifier if the call came from a signal, or 0 otherwise

boost::posix_time::time_duration freedm::broker::CBroker::TimeRemaining

(

)

Description:

Returns how much time is remaining in the active module's phase. The result can be negative if the module has exceeded its allotted execution time.

Precondition:

The Change Phase function has been called at least once. This should have occured by the time the first module is ready to look at the remaining time.

Postcondition:

None

Returns

A time_duration describing the amount of time remaining in the phase.

void freedm::broker::CBroker::Worker ( )

private

Description:

The worker determines the active module and execute the first task in that module's queue, before rescheduling itself.

Precondition:

None

Postcondition:

If there are tasks in the module's queue, the first task in the queue will be run, and the work will schedule itself to run again through the ioservice. If there are no tasks in the queue, the worker will stop.

Member Data Documentation

TimerAlloc freedm::broker::CBroker::m_allocs

private

bool freedm::broker::CBroker::m_busy

private

TimerHandle freedm::broker::CBroker::m_handlercounter

private

boost::asio::io_service freedm::broker::CBroker::m_ioService

private

boost::posix_time::ptime freedm::broker::CBroker::m_last_alignment

private

ModuleVector freedm::broker::CBroker::m_modules

private

NextTimeMap freedm::broker::CBroker::m_nexttime

private

NextTimeMap freedm::broker::CBroker::m_ntexpired

private

PhaseMarker freedm::broker::CBroker::m_phase

private

boost::posix_time::ptime freedm::broker::CBroker::m_phaseends

private

boost::asio::deadline_timer freedm::broker::CBroker::m_phasetimer

private

ReadyMap freedm::broker::CBroker::m_ready

private

boost::mutex freedm::broker::CBroker::m_schmutex

private

boost::asio::signal_set freedm::broker::CBroker::m_signals

private

bool freedm::broker::CBroker::m_stopping

private

boost::mutex freedm::broker::CBroker::m_stoppingMutex

private

boost::shared_ptr<CClockSynchronizer> freedm::broker::CBroker::m_synchronizer

private

TimersMap freedm::broker::CBroker::m_timers

private

---

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

• /home/docs/checkouts/readthedocs.org/user_builds/freedm/checkouts/latest/Broker/src/CBroker.hpp
• /home/docs/checkouts/readthedocs.org/user_builds/freedm/checkouts/latest/Broker/src/CBroker.cpp