eventq.hh revision 395
1/*
2 * Copyright (c) 2003 The Regents of The University of Michigan
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met: redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer;
9 * redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution;
12 * neither the name of the copyright holders nor the names of its
13 * contributors may be used to endorse or promote products derived from
14 * this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/* @file
30 * EventQueue interfaces
31 */
32
33#ifndef __EVENTQ_HH__
34#define __EVENTQ_HH__
35
36#include <assert.h>
37
38#include <algorithm>
39#include <map>
40#include <string>
41#include <vector>
42
43#include "sim/host.hh"	// for Tick
44
45#include "base/fast_alloc.hh"
46#include "sim/serialize.hh"
47#include "base/trace.hh"
48
49class EventQueue;	// forward declaration
50
51/*
52 * An item on an event queue.  The action caused by a given
53 * event is specified by deriving a subclass and overriding the
54 * process() member function.
55 */
56class Event : public Serializable, public FastAlloc
57{
58    friend class EventQueue;
59
60  private:
61    /// queue to which this event belongs (though it may or may not be
62    /// scheduled on this queue yet)
63    EventQueue *queue;
64
65    Event *next;
66
67    Tick _when;	//!< timestamp when event should be processed
68    int _priority;	//!< event priority
69    char _flags;
70
71  protected:
72    enum Flags {
73        None = 0x0,
74        Squashed = 0x1,
75        Scheduled = 0x2,
76        AutoDelete = 0x4,
77        AutoSerialize = 0x8
78    };
79
80    bool getFlags(Flags f) const { return (_flags & f) == f; }
81    void setFlags(Flags f) { _flags |= f; }
82    void clearFlags(Flags f) { _flags &= ~f; }
83
84  protected:
85    EventQueue *theQueue() const { return queue; }
86
87#if TRACING_ON
88    Tick when_created;	//!< Keep track of creation time For debugging
89    Tick when_scheduled;	//!< Keep track of creation time For debugging
90
91    virtual void trace(const char *action);	//!< trace event activity
92#else
93    void trace(const char *) {}
94#endif
95
96    unsigned annotated_value;
97
98  public:
99
100    /*
101     * Event constructor
102     * @param queue that the event gets scheduled on
103     */
104    Event(EventQueue *q, int p = 0)
105        : queue(q), next(NULL), _priority(p), _flags(None),
106#if TRACING_ON
107          when_created(curTick), when_scheduled(0),
108#endif
109          annotated_value(0)
110    {
111    }
112
113    ~Event() {}
114
115    virtual std::string name() const {
116        return csprintf("Event_%x", (uintptr_t)this);
117    }
118
119    /// Determine if the current event is scheduled
120    bool scheduled() const { return getFlags(Scheduled); }
121
122    /// Schedule the event with the current priority or default priority
123    void schedule(Tick t);
124
125    /// Schedule the event with a specific priority
126    void schedule(Tick t, int priority);
127
128    /// Reschedule the event with the current priority
129    void reschedule(Tick t);
130
131    /// Reschedule the event with a specific priority
132    void reschedule(Tick t, int priority);
133
134    /// Remove the event from the current schedule
135    void deschedule();
136
137    /// Return a C string describing the event.  This string should
138    /// *not* be dynamically allocated; just a const char array
139    /// describing the event class.
140    virtual const char *description();
141
142    /// Dump the current event data
143    void dump();
144
145    /*
146     * This member function is invoked when the event is processed
147     * (occurs).  There is no default implementation; each subclass
148     * must provide its own implementation.  The event is not
149     * automatically deleted after it is processed (to allow for
150     * statically allocated event objects).
151     *
152     * If the AutoDestroy flag is set, the object is deleted once it
153     * is processed.
154     */
155    virtual void process() = 0;
156
157    void annotate(unsigned value) { annotated_value = value; };
158    unsigned annotation() { return annotated_value; }
159
160    /// Squash the current event
161    void squash() { setFlags(Squashed); }
162
163    /// Check whether the event is squashed
164    bool squashed() { return getFlags(Squashed); }
165
166    /// Get the time that the event is scheduled
167    Tick when() const { return _when; }
168
169    /// Get the event priority
170    int priority() const { return _priority; }
171
172    struct priority_compare :
173    public std::binary_function<Event *, Event *, bool>
174    {
175        bool operator()(const Event *l, const Event *r) const {
176            return l->when() >= r->when() || l->priority() >= r->priority();
177        }
178    };
179
180    virtual void serialize(std::ostream &os);
181    virtual void unserialize(Checkpoint *cp, const std::string &section);
182};
183
184template <class T, void (T::* F)()>
185void
186DelayFunction(Tick when, T *object)
187{
188    class DelayEvent : public Event
189    {
190      private:
191        T *object;
192
193      public:
194        DelayEvent(Tick when, T *o)
195            : Event(&mainEventQueue), object(o)
196            { setFlags(AutoDestroy); schedule(when); }
197        void process() { (object->*F)(); }
198        const char *description() { return "delay"; }
199    };
200
201    new DelayEvent(when, object);
202}
203
204/*
205 * Queue of events sorted in time order
206 */
207class EventQueue : public Serializable
208{
209  protected:
210    std::string objName;
211
212  private:
213    Event *head;
214
215    void insert(Event *event);
216    void remove(Event *event);
217
218  public:
219
220    // constructor
221    EventQueue(const std::string &n)
222        : objName(n), head(NULL)
223    {}
224
225    virtual std::string name() const { return objName; }
226
227    // schedule the given event on this queue
228    void schedule(Event *ev);
229    void deschedule(Event *ev);
230    void reschedule(Event *ev);
231
232    Tick nextTick() { return head->when(); }
233    void serviceOne();
234
235    // process all events up to the given timestamp.  we inline a
236    // quick test to see if there are any events to process; if so,
237    // call the internal out-of-line version to process them all.
238    void serviceEvents(Tick when) {
239        while (!empty()) {
240            if (nextTick() > when)
241                break;
242
243            assert(head->when() >= when && "event scheduled in the past");
244            serviceOne();
245        }
246    }
247
248    // default: process all events up to 'now' (curTick)
249    void serviceEvents() { serviceEvents(curTick); }
250
251    // return true if no events are queued
252    bool empty() { return head == NULL; }
253
254    void dump();
255
256    Tick nextEventTime() { return empty() ? curTick : head->when(); }
257
258    virtual void serialize(std::ostream &os);
259    virtual void unserialize(Checkpoint *cp, const std::string &section);
260};
261
262
263//////////////////////
264//
265// inline functions
266//
267// can't put these inside declaration due to circular dependence
268// between Event and EventQueue classes.
269//
270//////////////////////
271
272// schedule at specified time (place on event queue specified via
273// constructor)
274inline void
275Event::schedule(Tick t)
276{
277    assert(!scheduled());
278    setFlags(Scheduled);
279#if TRACING_ON
280    when_scheduled = curTick;
281#endif
282    _when = t;
283    queue->schedule(this);
284}
285
286inline void
287Event::schedule(Tick t, int p)
288{
289    _priority = p;
290    schedule(t);
291}
292
293inline void
294Event::deschedule()
295{
296    assert(scheduled());
297
298    clearFlags(Squashed);
299    clearFlags(Scheduled);
300    queue->deschedule(this);
301}
302
303inline void
304Event::reschedule(Tick t)
305{
306    assert(scheduled());
307    clearFlags(Squashed);
308
309#if TRACING_ON
310    when_scheduled = curTick;
311#endif
312    _when = t;
313    queue->reschedule(this);
314}
315
316inline void
317Event::reschedule(Tick t, int p)
318{
319    _priority = p;
320    reschedule(t);
321}
322
323inline void
324EventQueue::schedule(Event *event)
325{
326    insert(event);
327    if (DTRACE(Event))
328        event->trace("scheduled");
329}
330
331inline void
332EventQueue::deschedule(Event *event)
333{
334    remove(event);
335    if (DTRACE(Event))
336        event->trace("descheduled");
337}
338
339inline void
340EventQueue::reschedule(Event *event)
341{
342    remove(event);
343    insert(event);
344    if (DTRACE(Event))
345        event->trace("rescheduled");
346}
347
348
349//////////////////////
350//
351// Main Event Queue
352//
353// Events on this queue are processed at the *beginning* of each
354// cycle, before the pipeline simulation is performed.
355//
356// defined in eventq.cc
357//
358//////////////////////
359extern EventQueue mainEventQueue;
360
361#endif // __EVENTQ_HH__
362