Project

General

Profile

Statistics
| Branch: | Revision:

root / include / clistener.h @ 2f5cc443

History | View | Annotate | Download (5.92 KB)

1 01873262 Georg Kunz
//==========================================================================
2
//  CLISTENER.H - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//==========================================================================
7
8
/*--------------------------------------------------------------*
9
  Copyright (C) 1992-2008 Andras Varga
10
  Copyright (C) 2006-2008 OpenSim Ltd.
11

12
  This file is distributed WITHOUT ANY WARRANTY. See the file
13
  `license' for details on this and other legal matters.
14
*--------------------------------------------------------------*/
15
16
#ifndef __CLISTENER_H
17
#define __CLISTENER_H
18
19
#include "simtime_t.h"
20
#include "cobject.h"
21
22
NAMESPACE_BEGIN
23
24
class cComponent;
25
26
/**
27
 * Signal handle.
28
 *
29
 * @see cComponent::subscribe(), cComponent::unsubscribe(), cComponent::emit()
30
 * and cIListener
31
 *
32
 * @ingroup Signals
33
 */
34
typedef int simsignal_t;
35
36
#define SIMSIGNAL_NULL   ((simsignal_t)-1)
37
38
39
/**
40
 * Interface for listeners in a simulation model.
41
 *
42
 * This class performs subscription counting, in order to make sure that
43
 * when the destructor runs, the object is no longer subscribed anywhere.
44
 *
45
 * @see cComponent::subscribe(), cComponent::unsubscribe()
46
 *
47
 * @ingroup Signals
48
 */
49
class SIM_API cIListener
50
{
51
    friend class cComponent; // for subscribecount
52
    friend class ResultFilter; // for subscribecount
53
  private:
54
    int subscribecount;
55
  public:
56
    cIListener();
57
    virtual ~cIListener();
58
59
    /**
60
     * Receive an emitted long value. The "source" argument is the channel
61
     * or module on which the emit() method was invoked, and NOT the one at
62
     * which this listener is subscribed.
63
     *
64
     * It is not allowed inside a receiveSignal() call to unsubscribe from
65
     * the signal being received -- it will cause an error to be thrown.
66
     * (This is to prevent interesting cases when the listener list is being
67
     * modified while the component iterates on it. The alternative would be
68
     * to make a temporary copy of the listener list each time, but this is
69
     * not done for performance reasons.)
70
     */
71
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, long l) = 0;
72
73
    /** Receive an emitted unsigned long value. See receiveSignal(cComponent*,simsignal_t,long) for more info */
74
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, unsigned long l) = 0;
75
76
    /** Receive an emitted double value. See receiveSignal(cComponent*,simsignal_t,long) for more info */
77
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, double d) = 0;
78
79
    /** Receive an emitted simtime_t value. See receiveSignal(cComponent*,simsignal_t,long) for more info */
80
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, const SimTime& t) = 0;
81
82
    /** Receive an emitted string value. See receiveSignal(cComponent*,simsignal_t,long) for more info */
83
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, const char *s) = 0;
84
85
    /** Receive an emitted cObject value. See receiveSignal(cComponent*,simsignal_t,long) for more info */
86
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, cObject *obj) = 0;
87
88
    /**
89
     * Called by a component on its local listeners after the component's
90
     * finish() method was called. If the listener is subscribed to multiple
91
     * signals or at multiple components, the method will be called multiple times.
92
     * Note that finish() methods in general are not invoked if the simulation
93
     * terminates with an error.
94
     */
95
    virtual void finish(cComponent *component, simsignal_t signalID) {}
96
97
    /**
98
     * Called when this object was added to the given component's given signal
99
     * as a listener. Note that this method will only be called from subscribe()
100
     * if this listener was not already subscribed.
101
     */
102
    virtual void subscribedTo(cComponent *component, simsignal_t signalID) {}
103
104
    /**
105
     * Called when this object was removed from the given component's listener
106
     * list for the given signal. Note that it will not be called from
107
     * unsubscribe() if this listener was not actually subscribed before.
108
     *
109
     * This method is also called from cComponent's destructor for all
110
     * listeners, so at this point it is not safe to cast the component pointer
111
     * to any other type. Also, the method may be called several times (i.e.
112
     * if the listener was subscribed to multiple signals).
113
     *
114
     * It is OK for the listener to delete itself in this method (<tt>delete
115
     * this</tt>). However, since this method may be called more than once
116
     * if the listener is subscribed multiple times (see above), one must be
117
     * careful to prevent double deletion, e.g. by reference counting.
118
     */
119
    virtual void unsubscribedFrom(cComponent *component, simsignal_t signalID) {}
120
121
    /**
122
     * Returns the number of listener lists that contain this listener.
123
     */
124
    int getSubscribeCount() const  { return subscribecount; }
125
};
126
127
/**
128
 * A do-nothing implementation of cIListener, suitable as a base class
129
 * for other listeners. The user needs to redefine one or more of the
130
 * overloaded receiveSignal() methods; the rest will throw a "Data type
131
 * not supported" error.
132
 *
133
 * @ingroup Signals
134
 */
135
class SIM_API cListener : public cIListener
136
{
137
  protected:
138
    /** Utility function, throws a "data type not supported" error. */
139
    virtual void unsupportedType(simsignal_t signalID, const char *dataType);
140
  public:
141
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, long l);
142
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, unsigned long l);
143
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, double d);
144
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, const SimTime& t);
145
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, const char *s);
146
    virtual void receiveSignal(cComponent *source, simsignal_t signalID, cObject *obj);
147
};
148
149
NAMESPACE_END
150
151
#endif