gem5  v21.1.0.2
Classes | Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
gem5::EventQueue Class Reference

Queue of events sorted in time order. More...

#include <eventq.hh>

Classes

class  ScopedMigration
 
class  ScopedRelease
 

Public Member Functions

 EventQueue (const std::string &n)
 
void schedule (Event *event, Tick when, bool global=false)
 Schedule the given event on this queue. More...
 
void deschedule (Event *event)
 Deschedule the specified event. More...
 
void reschedule (Event *event, Tick when, bool always=false)
 Reschedule the specified event. More...
 
Tick nextTick () const
 
void setCurTick (Tick newVal)
 
Tick getCurTick () const
 While curTick() is useful for any object assigned to this event queue, if an object that is assigned to another event queue (or a non-event object) need to access the current tick of this event queue, this function is used. More...
 
EventgetHead () const
 
EventserviceOne ()
 
void serviceEvents (Tick when)
 process all events up to the given timestamp. More...
 
bool empty () const
 Returns true if no events are queued. More...
 
void dump () const
 This is a debugging function which will print everything on the event queue. More...
 
bool debugVerify () const
 
void handleAsyncInsertions ()
 Function for moving events from the async_queue to the main queue. More...
 
virtual void wakeup (Tick when=(Tick) -1)
 Function to signal that the event loop should be woken up because an event has been scheduled by an agent outside the gem5 event loop(s) whose event insertion may not have been noticed by gem5. More...
 
EventreplaceHead (Event *s)
 function for replacing the head of the event queue, so that a different set of events can run without disturbing events that have already been scheduled. More...
 
void checkpointReschedule (Event *event)
 Reschedule an event after a checkpoint. More...
 
virtual ~EventQueue ()
 
virtual const std::string name () const
 
void name (const std::string &st)
 
void lock ()
 Provide an interface for locking/unlocking the event queue. More...
 
void unlock ()
 

Private Member Functions

void insert (Event *event)
 Insert / remove event from the queue. More...
 
void remove (Event *event)
 
void asyncInsert (Event *event)
 Function for adding events to the async queue. More...
 
 EventQueue (const EventQueue &)
 

Private Attributes

std::string objName
 
Eventhead
 
Tick _curTick
 
UncontendedMutex async_queue_mutex
 Mutex to protect async queue. More...
 
std::list< Event * > async_queue
 List of events added by other threads to this event queue. More...
 
UncontendedMutex service_mutex
 Lock protecting event handling. More...
 

Friends

void curEventQueue (EventQueue *)
 

Detailed Description

Queue of events sorted in time order.

Events are scheduled (inserted into the event queue) using the schedule() method. This method either inserts a synchronous or asynchronous event.

Synchronous events are scheduled using schedule() method with the argument 'global' set to false (default). This should only be done from a thread holding the event queue lock (EventQueue::service_mutex). The lock is always held when an event handler is called, it can therefore always insert events into its own event queue unless it voluntarily releases the lock.

Events can be scheduled across thread (and event queue borders) by either scheduling asynchronous events or taking the target event queue's lock. However, the lock should never be taken directly since this is likely to cause deadlocks. Instead, code that needs to schedule events in other event queues should temporarily release its own queue and lock the new queue. This prevents deadlocks since a single thread never owns more than one event queue lock. This functionality is provided by the ScopedMigration helper class. Note that temporarily migrating between event queues can make the simulation non-deterministic, it should therefore be limited to cases where that can be tolerated (e.g., handling asynchronous IO or fast-forwarding in KVM).

Asynchronous events can also be scheduled using the normal schedule() method with the 'global' parameter set to true. Unlike the previous queue migration strategy, this strategy is fully deterministic. This causes the event to be inserted in a separate queue of asynchronous events (async_queue), which is merged main event queue at the end of each simulation quantum (by calling the handleAsyncInsertions() method). Note that this implies that such events must happen at least one simulation quantum into the future, otherwise they risk being scheduled in the past by handleAsyncInsertions().

Definition at line 622 of file eventq.hh.

Constructor & Destructor Documentation

◆ EventQueue()

gem5::EventQueue::EventQueue ( const EventQueue )
private

◆ ~EventQueue()

virtual gem5::EventQueue::~EventQueue ( )
inlinevirtual

Definition at line 971 of file eventq.hh.

References deschedule(), empty(), and getHead().

Member Function Documentation

◆ asyncInsert()

void gem5::EventQueue::asyncInsert ( Event event)
private

Function for adding events to the async queue.

The added events are added to main event queue later. Threads, other than the owning thread, should call this function instead of insert().

Definition at line 424 of file eventq.cc.

References async_queue, async_queue_mutex, gem5::MipsISA::event, gem5::UncontendedMutex::lock(), and gem5::UncontendedMutex::unlock().

Referenced by schedule().

◆ checkpointReschedule()

void gem5::EventQueue::checkpointReschedule ( Event event)

Reschedule an event after a checkpoint.

Since events don't know which event queue they belong to, parent objects need to reschedule events themselves. This method conditionally schedules an event that has the Scheduled flag set. It should be called by parent objects after unserializing an object.

@warn Only use this method after unserializing an Event.

Definition at line 280 of file eventq.cc.

References gem5::MipsISA::event, insert(), and gem5::EventBase::Scheduled.

◆ debugVerify()

bool gem5::EventQueue::debugVerify ( ) const

◆ getHead()

Event* gem5::EventQueue::getHead ( ) const
inline

Definition at line 858 of file eventq.hh.

References head.

Referenced by gem5::ruby::RubySystem::memWriteback(), and ~EventQueue().

◆ handleAsyncInsertions()

void gem5::EventQueue::handleAsyncInsertions ( )

Function for moving events from the async_queue to the main queue.

Definition at line 432 of file eventq.cc.

References async_queue, async_queue_mutex, curEventQueue, insert(), gem5::UncontendedMutex::lock(), and gem5::UncontendedMutex::unlock().

Referenced by gem5::doSimLoop(), and gem5::GlobalSyncEvent::BarrierEvent::process().

◆ insert()

void gem5::EventQueue::insert ( Event event)
private

Insert / remove event from the queue.

Should only be called by thread operating this queue.

Definition at line 112 of file eventq.cc.

References gem5::MipsISA::event, head, gem5::Event::insertBefore(), and gem5::Event::nextBin.

Referenced by checkpointReschedule(), handleAsyncInsertions(), reschedule(), and schedule().

◆ lock()

void gem5::EventQueue::lock ( )
inline

Provide an interface for locking/unlocking the event queue.

@warn Do NOT use these methods directly unless you really know what you are doing. Incorrect use can easily lead to simulator deadlocks.

See also
EventQueue::ScopedMigration.
EventQueue::ScopedRelease
EventQueue

Definition at line 954 of file eventq.hh.

References gem5::UncontendedMutex::lock(), and service_mutex.

Referenced by gem5::DistIface::RecvScheduler::pushPacket(), gem5::DistIface::recvThreadFunc(), gem5::EventQueue::ScopedMigration::ScopedMigration(), serviceOne(), gem5::EventQueue::ScopedMigration::~ScopedMigration(), and gem5::EventQueue::ScopedRelease::~ScopedRelease().

◆ nextTick()

Tick gem5::EventQueue::nextTick ( ) const
inline

◆ remove()

void gem5::EventQueue::remove ( Event event)
private

Definition at line 166 of file eventq.cc.

References gem5::MipsISA::event, head, gem5::Event::nextBin, panic, and gem5::Event::removeItem().

Referenced by deschedule(), and reschedule().

◆ replaceHead()

Event * gem5::EventQueue::replaceHead ( Event s)

function for replacing the head of the event queue, so that a different set of events can run without disturbing events that have already been scheduled.

Already scheduled events can be processed by replacing the original head back. USING THIS FUNCTION CAN BE DANGEROUS TO THE HEALTH OF THE SIMULATOR. NOT RECOMMENDED FOR USE.

Definition at line 356 of file eventq.cc.

References head, gem5::ArmISA::s, and gem5::ArmISA::t.

Referenced by gem5::ruby::RubySystem::startup().

◆ serviceOne()

Event * gem5::EventQueue::serviceOne ( )

◆ setCurTick()

void gem5::EventQueue::setCurTick ( Tick  newVal)
inline

Definition at line 844 of file eventq.hh.

References _curTick.

Referenced by serviceEvents(), serviceOne(), and gem5::EventManager::setCurTick().

◆ unlock()

void gem5::EventQueue::unlock ( )
inline

Friends And Related Function Documentation

◆ curEventQueue

void curEventQueue ( EventQueue q)
friend

Member Data Documentation

◆ _curTick

Tick gem5::EventQueue::_curTick
private

Definition at line 629 of file eventq.hh.

Referenced by getCurTick(), and setCurTick().

◆ async_queue

std::list<Event*> gem5::EventQueue::async_queue
private

List of events added by other threads to this event queue.

Definition at line 635 of file eventq.hh.

Referenced by asyncInsert(), and handleAsyncInsertions().

◆ async_queue_mutex

UncontendedMutex gem5::EventQueue::async_queue_mutex
private

Mutex to protect async queue.

Definition at line 632 of file eventq.hh.

Referenced by asyncInsert(), and handleAsyncInsertions().

◆ head

Event* gem5::EventQueue::head
private

Definition at line 628 of file eventq.hh.

Referenced by debugVerify(), dump(), empty(), getHead(), insert(), nextTick(), remove(), replaceHead(), and serviceOne().

◆ objName

std::string gem5::EventQueue::objName
private

Definition at line 627 of file eventq.hh.

Referenced by name().

◆ service_mutex

UncontendedMutex gem5::EventQueue::service_mutex
private

Lock protecting event handling.

This lock is always taken when servicing events. It is assumed that the thread scheduling new events (not asynchronous events though) have taken this lock. This is normally done by serviceOne() since new events are typically scheduled as a response to an earlier event.

This lock is intended to be used to temporarily steal an event queue to support inter-thread communication when some deterministic timing can be sacrificed for speed. For example, the KVM CPU can use this support to access devices running in a different thread.

See also
EventQueue::ScopedMigration.
EventQueue::ScopedRelease
EventQueue::lock()
EventQueue::unlock()

Definition at line 657 of file eventq.hh.

Referenced by lock(), and unlock().


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

Generated on Tue Sep 21 2021 12:27:31 for gem5 by doxygen 1.8.17