Project

General

Profile

Statistics
| Branch: | Revision:

root / include / coutvector.h @ b781545c

History | View | Annotate | Download (8.37 KB)

1
//==========================================================================
2
//  COUTVECTOR.H - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//
7
//  Declaration of the following classes:
8
//    cOutVector : represents an output vector
9
//
10
//==========================================================================
11

    
12
/*--------------------------------------------------------------*
13
  Copyright (C) 1992-2008 Andras Varga
14
  Copyright (C) 2006-2008 OpenSim Ltd.
15

16
  This file is distributed WITHOUT ANY WARRANTY. See the file
17
  `license' for details on this and other legal matters.
18
*--------------------------------------------------------------*/
19

    
20
#ifndef __COUTVECTOR_H
21
#define __COUTVECTOR_H
22

    
23
#include <stdio.h>
24
#include "cownedobject.h"
25
#include "simtime_t.h"
26

    
27
NAMESPACE_BEGIN
28

    
29

    
30
/**
31
 * Prototype for callback functions that are used to notify graphical user
32
 * interfaces when values are recorded to an output vector (see cOutVector).
33
 * @ingroup EnumsTypes
34
 */
35
typedef void (*RecordFunc)(void *, simtime_t, double, double);
36

    
37
class cEnum;
38

    
39

    
40
/**
41
 * Responsible for recording vector simulation results (an output vector).
42
 * A cOutVector object can write doubles to the output vector file
43
 * (or any another device determined by the current cOutputVectorManager).
44
 *
45
 * @ingroup Statistics
46
 */
47
class SIM_API cOutVector : public cNoncopyableOwnedObject
48
{
49
  protected:
50
    enum {
51
      FL_ENABLED = 4,      // flag: when false, record() method will do nothing
52
      FL_RECORDWARMUP = 8, // flag: when set, object records data during warmup period as well
53
    };
54

    
55
    void *handle;        // identifies output vector for the output vector manager
56
    simtime_t last_t;    // last timestamp written, needed to ensure increasing timestamp order
57
    long num_received;   // total number of values passed to the output vector object
58
    long num_stored;     // number of values actually stored
59

    
60
    // the following members will be used directly by inspectors
61
    RecordFunc record_in_inspector; // to notify inspector about file writes
62
    void *data_for_inspector;
63

    
64
  public:
65
    // internal: called from behind cEnvir
66
    void setCallback(RecordFunc f, void *d) {record_in_inspector=f; data_for_inspector=d;}
67

    
68
  public:
69
    enum Type { TYPE_INT, TYPE_DOUBLE, TYPE_ENUM };
70
    enum InterpolationMode { NONE, SAMPLE_HOLD, BACKWARD_SAMPLE_HOLD, LINEAR };
71

    
72
  public:
73
    /** @name Constructors, destructor, assignment */
74
    //@{
75
    /**
76
     * Constructor.
77
     */
78
    explicit cOutVector(const char *name=NULL);
79

    
80
    /**
81
     * Destructor.
82
     */
83
    virtual ~cOutVector();
84
    //@}
85

    
86
    /** @name Redefined cObject member functions. */
87
    //@{
88

    
89
    /**
90
     * Sets the name of the object. It is not possible to call this method after the
91
     * first call to record().
92
     */
93
    virtual void setName(const char *name);
94

    
95
    /**
96
     * Produces a one-line description of the object's contents.
97
     * See cObject for more details.
98
     */
99
    virtual std::string info() const;
100

    
101
    /**
102
     * Packing and unpacking cannot be supported with this class.
103
     * This methods raises an error.
104
     */
105
    virtual void parsimPack(cCommBuffer *buffer);
106

    
107
    /**
108
     * Packing and unpacking cannot be supported with this class.
109
     * This methods raises an error.
110
     */
111
    virtual void parsimUnpack(cCommBuffer *buffer);
112
    //@}
113

    
114
    /** @name Metadata annotations. */
115
    //@{
116
    /**
117
     * Associate the vector with an enum defined in a msg file.
118
     * This information gets recorded into the output vector file and
119
     * may be used by result analysis tools.
120
     * cOutVector does not verify that recorded values actually comply
121
     * with this annotation.
122
     */
123
    virtual void setEnum(const char *registeredEnumName);
124

    
125
    /**
126
     * Associate the vector with an enum. The enum name as well as the
127
     * symbols and their integer values will get recorded into the output
128
     * vector file, and may be used by result analysis tools.
129
     * cOutVector does not verify that recorded values actually comply
130
     * with this annotation.
131
     */
132
    virtual void setEnum(cEnum *enumDecl);
133

    
134
    /**
135
     * Annotate the vector with a physical unit (like "s", "mW" or "bytes").
136
     * This information gets recorded into the output vector file, and
137
     * may be used by result analysis tools.
138
     */
139
    virtual void setUnit(const char *unit);
140

    
141
    /**
142
     * Annotate the vector with a data type. This information gets recorded
143
     * into the output vector file, and may be used by result analysis tools.
144
     * cOutVector does not verify that recorded values actually comply with
145
     * this annotation.
146
     */
147
    virtual void setType(Type type);
148

    
149
    /**
150
     * Annotate the vector with an interpolation mode. This information
151
     * gets recorded into the output vector file, and may be used
152
     * by result analysis tools as a hint for choosing a plotting style.
153
     */
154
    virtual void setInterpolationMode(InterpolationMode mode);
155

    
156
    /**
157
     * Annotate the vector with a minimum value. This information gets
158
     * recorded into the output vector file and may be used
159
     * by result analysis tools. cOutVector does not verify that
160
     * recorded values actually comply with this annotation.
161
     */
162
    virtual void setMin(double minValue);
163

    
164
    /**
165
     * Annotate the vector with a maximum value. This information gets
166
     * recorded into the output vector file and may be used
167
     * by result analysis tools. cOutVector does not verify that
168
     * recorded values actually comply with this annotation.
169
     */
170
    virtual void setMax(double maxValue);
171
    //@}
172

    
173
    /** @name Writing to output vectors. */
174
    //@{
175
    /**
176
     * Records the value with the current simulation time as timestamp.
177
     *
178
     * The return value is true if the data was actually recorded, and false
179
     * if it was not recorded (because of filtering, etc.)
180
     */
181
    virtual bool record(double value);
182

    
183
    /**
184
     * Convenience method, delegates to record(double).
185
     */
186
    virtual bool record(SimTime value)  {return record(value.dbl());}
187

    
188
    /**
189
     * Records the value with the given time as timestamp. Values must be
190
     * recorded in increasing timestamp order, that is, it is not possible
191
     * to record a value with a timestamp that is less than that of the
192
     * last recorded value.
193
     *
194
     * The return value is true if the data was actually recorded, and false
195
     * if it was not recorded (because of filtering, etc.)
196
     */
197
    virtual bool recordWithTimestamp(simtime_t t, double value);
198

    
199
    /**
200
     * Convenience method, delegates to recordWithTimestamp(simtime_t, double).
201
     */
202
    virtual bool recordWithTimestamp(simtime_t t, SimTime value) {return recordWithTimestamp(t, value.dbl());}
203

    
204
    /**
205
     * Enables recording data via this object. (It is enabled by default.)
206
     */
207
    virtual void enable()  {setFlag(FL_ENABLED,true);}
208

    
209
    /**
210
     * Disables recording data via this object. record() methods will return
211
     * false without doing anything.
212
     */
213
    virtual void disable()  {setFlag(FL_ENABLED,false);}
214

    
215
    /**
216
     * Enables/disables recording data via this object.
217
     * @see enable(), disable()
218
     */
219
    virtual void setEnabled(bool b)  {setFlag(FL_ENABLED,b);}
220

    
221
    /**
222
     * Returns true if recording the data is enabled, false otherwise.
223
     */
224
    virtual bool isEnabled() const  {return flags&FL_ENABLED;}
225

    
226
    /**
227
     * Enables/disables recording data during the warm-up period.
228
     * When set to false, record() calls will be ignored during
229
     * warm-up period.
230
     *
231
     * @see cSimulation::getWarmupPeriod()
232
     */
233
    virtual void setRecordDuringWarmupPeriod(bool b)  {setFlag(FL_RECORDWARMUP,b);}
234

    
235
    /**
236
     * Returns true if the object will record data during the warm-up period.
237
     * @see cSimulation::getWarmupPeriod()
238
     */
239
    virtual bool getRecordDuringWarmupPeriod() const  {return flags&FL_RECORDWARMUP;}
240

    
241
    /**
242
     * Returns the total number of values passed to the record() method of
243
     * this output vector object. This includes the values passed while
244
     * the object was disabled (see disable()).
245
     */
246
    long getValuesReceived() const  {return num_received;}
247

    
248
    /**
249
     * Returns the number of values actually stored by this output vector object.
250
     * The values passed while the object was disabled (via disable(),
251
     * environment configuration, filtering, etc.) do not count.
252
     */
253
    long getValuesStored() const  {return num_stored;}
254
    //@}
255
};
256

    
257
NAMESPACE_END
258

    
259

    
260
#endif
261

    
262