net_instaweb::Scheduler Class Reference

#include "scheduler.h"

Inheritance diagram for net_instaweb::Scheduler:

Classes
struct	CompareAlarms
class	Sequence

Public Member Functions
	Scheduler (ThreadSystem *thread_system, Timer *timer)
ThreadSystem::CondvarCapableMutex *	mutex () LOCK_RETURNED(mutex_)
void	DCheckLocked () EXCLUSIVE_LOCKS_REQUIRED(mutex())
	Optionally check that mutex is locked for debugging purposes.
void	BlockingTimedWaitMs (int64 timeout_ms) EXCLUSIVE_LOCKS_REQUIRED(mutex())
	Wait at most timeout_ms, or until Signal() is called. More...
void	BlockingTimedWaitUs (int64 timeout_us) EXCLUSIVE_LOCKS_REQUIRED(mutex())
void	TimedWaitMs (int64 timeout_ms, Function *callback) EXCLUSIVE_LOCKS_REQUIRED(mutex())
void	Signal () EXCLUSIVE_LOCKS_REQUIRED(mutex())
Alarm *	AddAlarmAtUs (int64 wakeup_time_us, Function *callback) LOCKS_EXCLUDED(mutex())
Alarm *	AddAlarmAtUsMutexHeld (int64 wakeup_time_us, Function *callback) EXCLUSIVE_LOCKS_REQUIRED(mutex())
bool	CancelAlarm (Alarm *alarm) EXCLUSIVE_LOCKS_REQUIRED(mutex())
bool	ProcessAlarmsOrWaitUs (int64 timeout_us) EXCLUSIVE_LOCKS_REQUIRED(mutex())
Timer *	timer ()
ThreadSystem *	thread_system ()
	Obtain the thread system used by the scheduler.
void	Wakeup ()
virtual void	RegisterWorker (QueuedWorkerPool::Sequence *w)
virtual void	UnregisterWorker (QueuedWorkerPool::Sequence *w)
int64	RunAlarms (bool *ran_alarms) EXCLUSIVE_LOCKS_REQUIRED(mutex())
Sequence *	NewSequence ()
	Creates a new sequence, controlled by the scheduler.

Protected Member Functions
virtual void	AwaitWakeupUntilUs (int64 wakeup_time_us)
bool	running_waiting_alarms () const

Friends
class	SchedulerTest

Detailed Description

Implements a simple scheduler that allows a thread to block until either time expires, or a condition variable is signaled. Also permits various alarms to be scheduled; these are lightweight short-lived callbacks that must be safely runnable from any thread in any lock state in which scheduler invocations occur. Finally, implements a hybrid between these: a callback that can be run when the condition variable is signaled.

This class is designed to be overridden, but only to re-implement its internal notion of blocking to permit time to be mocked by MockScheduler.

Member Function Documentation

Alarm* net_instaweb::Scheduler::AddAlarmAtUs	(	int64	wakeup_time_us,
		Function *	callback
	)

Alarms. The following two methods provide a mechanism for scheduling alarm tasks, each run at a particular time. Schedules an alarm for absolute time wakeup_time_us, using the passed-in Function* as the alarm callback. Returns the created Alarm. Performs outstanding work. The returned alarm will own the callback and will clean itself and the callback when it is run or cancelled. NOTE in particular that calls to CancelAlarm must ensure the callback has not been invoked yet. This is why the scheduler mutex must be held for CancelAlarm.

Will wakeup the scheduler if the time of the first alarm changed. It will also run any outstanding alarms. Both of these operations will result in temporarily dropping the lock. See also AddAlarmMutexHelp.

Todo:

TODO(jmaessen): Get rid of AddAlarmAtUs, or rename to AddAlarmAtUsAndRunOutstanding or similar.

Alarm* net_instaweb::Scheduler::AddAlarmAtUsMutexHeld	(	int64	wakeup_time_us,
		Function *	callback
	)

Adds a new alarm. Does not run any alarms, broadcast, or drop locks. See doc for AddAlarmAtUs.

virtual void net_instaweb::Scheduler::AwaitWakeupUntilUs ( int64  wakeup_time_us )

protectedvirtual

Internal method to await a wakeup event. Block until wakeup_time_us (an absolute time since the epoch), or until something interesting (such as a call to Signal) occurs. This is virtual to permit us to mock it out (the mock simply advances time). This maybe called with 0 in case where there are no timers currently active.

Reimplemented in net_instaweb::MockScheduler.

void net_instaweb::Scheduler::BlockingTimedWaitMs ( int64  timeout_ms )

inline

Wait at most timeout_ms, or until Signal() is called.

Condition-style methods: The following three methods provide a simple condition-variable-style interface that can be used to coordinate the threads sharing the scheduler.

bool net_instaweb::Scheduler::CancelAlarm

(

Alarm *

alarm

)

Cancels an alarm, calling the Cancel() method and deleting the alarm object. Scheduler mutex must be held before call to ensure that alarm is not called back before cancellation occurs. Doesn't perform outstanding work. Returns true if the cancellation occurred. If false is returned, the alarm is already being run / has been run in another thread; if the alarm deletes itself on Cancel(), it may no longer safely be used.

Note that once the user callback for the alarm returns it's no longer safe to call this (but this method is safe to call when the scheduler has committed to running the callback, it will just return false), so it's the caller's responsibility to properly synchronize between its callback and its invocation of this.

bool net_instaweb::Scheduler::ProcessAlarmsOrWaitUs

(

int64

timeout_us

)

Finally, ProcessAlarmsOrWaitUs provides a mechanism to ensure that pending alarms are executed in the absence of other scheduler activity. ProcessAlarmsOrWaitUs: handle outstanding alarms, or if there are none wait until the next wakeup and handle alarms then before relinquishing control. Idle no longer than timeout_us. Passing in timeout_us=0 will run without blocking.

Returns true if the scheduler has pending activities remaining, either runnable now or in the future.

virtual void net_instaweb::Scheduler::RegisterWorker ( QueuedWorkerPool::Sequence *  w )

virtual

These methods notify the scheduler of work sequences that may run work on it. They are only used for time simulations in MockScheduler and are no-ops during normal usage.

Reimplemented in net_instaweb::MockScheduler.

int64 net_instaweb::Scheduler::RunAlarms

(

bool *

ran_alarms

)

Run any alarms that have reached their deadline. Returns the time in microseconds of the next deadline, or 0 if no further deadlines loom. Sets *ran_alarms if non-NULL and any alarms were run, otherwise leaves it untouched.

void net_instaweb::Scheduler::Signal

(

)

Signal threads in BlockingTimedWait[Ms,Us] and invoke TimedWaitMs callbacks. Performs outstanding work, including any triggered by the signal, before returning; note that this means it may drop the scheduler lock internally while doing callback invocation, which is different from the usual condition variable signal semantics.

void net_instaweb::Scheduler::TimedWaitMs	(	int64	timeout_ms,
		Function *	callback
	)

Non-blocking invocation of callback either when Signal() is called, or after timeout_ms have passed. Ownership of callback passes to the scheduler, which deallocates it after invocation. mutex() must be held on the initial call, and is locked for the duration of callback. Note that callback may be invoked in a different thread from the calling thread.

Timer* net_instaweb::Scheduler::timer ( )

inline

Obtain the timer that the scheduler is using internally. Important if you and the scheduler want to agree on the passage of time.

void net_instaweb::Scheduler::Wakeup ( )

inline

Internal method to kick the system because something of interest to the overridden AwaitWakeup method has happened. Exported here because C++ naming hates you.

---

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

• pagespeed/kernel/thread/scheduler.h