Page Speed Optimization Libraries
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Public Member Functions | Protected Member Functions | Friends | List of all members
net_instaweb::Scheduler Class Reference

#include "scheduler.h"

Inheritance diagram for net_instaweb::Scheduler:


struct  CompareAlarms
class  Sequence

Public Member Functions

 Scheduler (ThreadSystem *thread_system, Timer *timer)
ThreadSystem::CondvarCapableMutexmutex () 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())
Timertimer ()
ThreadSystemthread_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())
SequenceNewSequence ()
 Creates a new sequence, controlled by the scheduler.

Protected Member Functions

virtual void AwaitWakeupUntilUs (int64 wakeup_time_us)
bool running_waiting_alarms () const


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(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)

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)

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)

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 ( )

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 ( )

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: