From 665092df5aad09ef55645cd3865b016d85f632be Mon Sep 17 00:00:00 2001 From: Marty Kraimer Date: Fri, 18 Feb 2011 14:16:09 -0500 Subject: [PATCH] update doc --- documentation/pvDataCpp.html | 737 ++++++++++++++++++++++------------- 1 file changed, 466 insertions(+), 271 deletions(-) diff --git a/documentation/pvDataCpp.html b/documentation/pvDataCpp.html index d4c80d5..868e6d7 100644 --- a/documentation/pvDataCpp.html +++ b/documentation/pvDataCpp.html @@ -9,15 +9,13 @@

EPICS pvDataCPP
-2011.01.31

+2011.02.18

TODO

@@ -25,150 +23,361 @@
- -

Introduction

+

Preface

This product is available via the open source license described at the end of this document.

+

pvData is one of a set of related projects:

+
+
pvData
+
Describes and implements structured data.
+
pvAccess
+
Provides networking for pvData.
+
pvIOC
+
Provides a database based on pvData together with record processing, + record scanning, and extensible support.
+
+ +

pvData

+ +

pvData describes and implements structured data. Interspection interfaces +are used to describe the data and for each type of data a data interface +provides a container to hold the data.

+ +

Introspection

+ +

pvData is modeled as a structured set of fields. A field has a name are a +type. The type must be one of:

+
+
scalar
+
A scalar has a scalar type which must be one of the following: +
+
boolean
+
Is always either true or false.
+
byte
+
An 8 bit signed integer.
+
short
+
A 16 bit signed integer.
+
int
+
A 32 bit signed integer.
+
long
+
A 64 bit signed integer.
+
float
+
A IEEE 32 bit float.
+
double
+
A IEEE 64 bit float.
+
string
+
A UTF8 string.
+
+
+
scalarArray
+
An array where all elements have the same scalar type.
+
structure
+
An array of fields. Each field can have a different type including + structure. Thus complex structured data is supported.
+
structureArray
+
An array of structure fields where each element has the exact same + introspection interface.
+
+ +

Introspection interface Field provides the name and type for the field. In +addition each type has an introspection interface: Scalar, ScalarArray, +Structure, and StructureArray.

+ +

Data

+ +

Interface PVField provides access to the common information of every data +container. In addition every possible type has an interface for accessing the +data:

+
+
scalar
+
The interfaces are PVBoolean, PVByte, PVShort, PVInt, PVLong, PVFloat, + PVDouble, and PVString.
+
scalarArray
+
The interfaces are PVBooleanArray, PVByteArray, PVShortArray, + PVIntArray, PVLongArray, PVFloatArray, PVDoubleArray, and + PVStringArray.
+
structure
+
The interface is PVStructure.
+
structureArray
+
The interface is PVStructureArray.
+
+ +

Property Structures

+ +

pvData provides support, via pvData structures and associated support, for +the following:

+
+
timeStamp
+
Time since the POSIX Epoch.
+
alarm
+
Alarm information.
+
display
+
Display Info
+
control
+
Control Info.
+
enumerated structrure
+
This is a pvData structure with two field: index and choices.
+
+ +

pvAccess

+ +

pvAccess provides client/server support for transmitting pvData objects. The +server must provide access to objects identified by name. Each object must have +a network wide unique name. A client issues a create channel request, +specifying the channel name in order to connect to the object on the server. +After the client has connected, it can issue the following types of request.

+
+
process
+
Asks that the channel process. The process semantics are determined by + the server.
+
get
+
Ask the get data from the server. The client can optionally ask the + server to process before returning data.
+
put
+
Puts data to the server. The server can optionally be asked to process + after receiving the data.
+
putGet
+
Puts data to the server, optionally ask the server to process, and then + get data from the server.
+
monitor
+
Request that the server send data to the client when new data is + available.
+
channelArray
+
This can get and put a sub- array.
+
channelRPC
+
This is similar to a putGet except that the server will create a new + PVStructure and send it to the client.
+
+ +

Associated with each type of request is a create method. The method has an +argument that allows the client to specify options. This argument is a top +level PVStructure called a pvRequest. The pvRequest is sent to the server. The +server side looks at what is requested and creates a top level PVStructrure +that will hold the data that is transfered between client and server. It then +sends the introspection info to the client side of pvAccess, which also creates +a top level PVStructure for holding data. At this time the client is notified +that it can start making requests. Thus when data is passed between client and +server it flows between the two top level PVStructures without requiring the +creation on new objects.

+ +

pvAccess provides many of the features of systems like CORBA and ICE +(Internet Communication Engine) but is designed to provide the following +features:

+
+
No IDL (Interface Definition Language) or associated compiler
+
The introspection interfaces replace the IDL.
+
Efficent use of network
+
Introspection info is only passed at creation time. For data requests + data is passed without any interspection information.
+ Multiple small objects are automatically combined into a single network + packet.
+ Large objects automatically span network packets.
+
+ +

pvIOC

+ +

IOC means Input/Output Controller, which is an EPICS term. A pvIOC is +modeled after an EPICS IOC but supports pvData instead of flat record +structures. At the present time the only implementation is in Java and called +javaIOC. The c++ implementaion will be called pvIOC and will be able to run in +an existing EPICS IOC.

+ +

Like an EPICS IOC a pvIOC provides the followig features:

+
+
Record Processing
+
A record can be processed, i.e. records are "smart". Each field can + optionally have attached support. When a record is asked to process the + support attacked to the top level PVStructure is called.
+
Record Scanning
+
A record can be scanned. Two types are supported: periodic and event. + The way event scanning is implemented provides both the I/O Intr scanning + and event scanning implemented by a EPICS IOC.
+
Extensible Support
+
Each field can optionally have support attached. Support is written to + process particular types of fields. At initilization support uses + interspection to look at the fields to which it is attached. If the + fields are not what it expects it reports a problem and terminates.
+
+ +

For pvAccess, the pvIOC provides the following:

+
+
Local channel implementation
+
The way the remote pvAccess server code works is to find one or more + local implementations of the Channel interface. It calls this to + implement the various operations it supports.
+
Access to data
+
Support is a available that allows a client to access an arbitrary set + of fields in a record. From this it creates a top level structure that + holds the copy of the fields. It also provides the support to copy date + between the copy and the record. It also provides support for monitor + queues and algortihms.
+
Access to EPICS V3 records
+
This is a local Channel implementation that privides support for + attaching to V3 records. It makes the V3 fields look like a pvData + structure.
+
Access to pvIOC records
+
This is a local Channel implementation that privides support for + attaching to pvIOC records.
+
+ +
+

Introduction

+
+

PVData is one of a set of related projects: pvData, pvAccess, and javaIOC. It describes and implements the data that the other projects use. Thus it is not useful by itself but understanding pvData is required in order to @@ -266,7 +475,7 @@ pvDataApp:

-

PVData Meta Language

+

PVData Meta Language

This section describes a meta language for describing pvData. Currently @@ -274,7 +483,7 @@ there are no plans for a parser for the meta language. It is used for documentation. Also the toString introspection and data methods described below present data in this format.

-

Definition

+

Definition

PVData supports structured data. All data appears as a top level structure. A structure has an ordered set of fields where each field has a 

     structure[] fieldName
           structureDef
           ...
-
Thus a structure array is an array where each element is a structure but all elements have the same introspection interface. For introspection the @@ -385,7 +593,7 @@ scalar data value depending on the type. Thus it is a comma separated set of values enclosed in [] White space is permitted surrounding each comma.

-

Example

+

Example

Define the following top level structure:

structure timeStamp
@@ -422,10 +630,10 @@ structure[] structureArrayExample
         double y 10.0
-

PV - User Description

+

PV - User Description

-

Overview

+

Overview

Directory pvDataApp/pv has header files that completely describe pvData. The implementation is provided in directory pvDataApp/factory. Test programs @@ -459,7 +667,7 @@ converting and copying data between fields.

alarm, etc. -

pvType

+

pvType

This provides C/C++ definitions for the pvData primitive types: boolean, byte, short, int, long, float, double, and string. Because pvData is network @@ -517,7 +725,7 @@ typedef std::string * StringBuilder;

A typedef is provided for an array of each of the primitive types.
-

Process Variable Reflection

+

Process Variable Reflection

This subsection describes pvIntrospect.h

@@ -532,7 +740,7 @@ especially important for arrays and structures so that a client can discover the type without requiring that a large data array or structure be transported over the network.

-

Type Description

+

Type Description

Types are defined as:

enum Type {
@@ -623,7 +831,7 @@ style="font-family: courier;">ScalarType

     
Convert the scalar type to a string.

 
 
-
Reflection Description

+
Reflection Description

 
 
This section describes the reflection interfaces which provide the
 following: 

@@ -852,7 +1060,7 @@ methods:

       structure->incReferenceCount() must be called before this method.
 
 
-
Standard Fields

+
Standard Fields

 
 
The file standardField.h has a class description for creating or sharing
 Field objects for standard fields. For each type of standard object two methods
@@ -990,12 +1198,12 @@ extern StandardField * getStandardField();
the section on Properties for a description of how these are defined. -

PVField - Data Interfaces

+

PVField - Data Interfaces

This section defines the Java Interfaces for accessing the data within a PV record.

-

PVField

+

PVField

PVField is the base interface for accessing data. A data structure consists of a top level PVStructure. Every field of every structure of every top level @@ -1102,7 +1310,7 @@ are:

. -

PVAuxInfo

+

PVAuxInfo

AuxInfo (Auxillary Information) is information about a field that is application specific. It will not be available outside the application that @@ -1139,7 +1347,7 @@ private:

Print all the auxInfos
-

PVScalar and extensions

+

PVScalar and extensions

class PVScalar : public PVField {
 public:
     virtual ~PVScalar();
@@ -1148,7 +1356,7 @@ protected:
     PVScalar(PVStructure *parent,ScalarConstPtr scalar);
 };
-
Primitive PVField types
+
Primitive PVField types

The interfaces for primitive data types are:

class PVBoolean : public PVScalar {
@@ -1237,7 +1445,7 @@ protected:
 private:
 };
-

PVArray and Extensions

+

PVArray and Extensions

PVArray is the base interface for all the other PV Array interfaces. It extends PVField and provides the @@ -1283,7 +1491,7 @@ private:

Specify if the capacity can be changed.
-
PVArray Extensions
+
PVArray Extensions

The interface for each array type has get and put methods which have the same arguments except for the data type. For example PVDoubleArray is:

@@ -1370,7 +1578,7 @@ that directly access the internal data array of a PVArray. This can be required for minimizing CPU overhead. In this case it is the applications responsibility to coordinate access to the array.

-
Complete set of PVArray Extensions
+
Complete set of PVArray Extensions
class PVScalarArray : public PVArray {
 public:
     virtual ~PVScalarArray();
@@ -1547,7 +1755,7 @@ protected:
 private:
 };
-

PVStructure

+

PVStructure

The interface for a structure is:

class PVStructure : public PVField,public BitSetSerializable {
@@ -1660,7 +1868,7 @@ private:
     
Specify the structure that this structure extends.

 
 
-
PVStructureArray

+
PVStructureArray

 
 
The interface for an array of structures is:

 
class StructureArrayData {
@@ -1733,7 +1941,7 @@ introspection interface must be used. The following shows an example:

 
 
Note that incReferenceCount is called before each element is created.

 
-
PVDataCreate

+
PVDataCreate

 
 
PVDataCreate is an interface that provides methods that create PVField
 interfaces. A factory is provided that creates PVDataCreate.

@@ -1815,7 +2023,7 @@ extern PVDataCreate * getPVDataCreate();

       before calling this method.
 
 
-
Standard Data Fields

+
Standard Data Fields

 
 
A class StandardPVField has methods for creating standard data fields. Like
 class StandardField it has two forms of the methods which create a field, one
@@ -1870,7 +2078,7 @@ public:
     PVStructure * powerSupply(PVStructure *parent);
 };
-

Convert

+

Convert

NOTE about copying immutable array fields. If an entire immutable array field is copied to another array that has the same elementType, both offsets @@ -1984,18 +2192,18 @@ for code that implements toString It generates a newline and inserts blanks at the beginning of the newline.

-

Namespace, Typedefs, and Memory +

Namespace, Typedefs, and Memory Management

-

Namespace

+

Namespace

All code in project pvDataCPP appears in namespace: 

namespace epics { namespace pvData {
      // ...
 }}
-

typedefs

+

typedefs

As described above pvType.h provides C++ typdefs for the pvData primitive types.

@@ -2047,9 +2255,9 @@ typedef String * StringArray;
An array of the specified type NOT a pointer to the type.
-

Memory Managemment

+

Memory Managemment

-

NoDefaultMethods

+

NoDefaultMethods

Any class that does not want the compiler to generate default methods can privately extend the following class which is defined in file @@ -2065,7 +2273,7 @@ private: NoDefaultMethods & operator=(const NoDefaultMethods &); }; -

PVData introspection objects

+

PVData introspection objects

Introspection objects are meant to be shared. The constructors and destructors are all private or protected so that an introspection object can @@ -2085,7 +2293,7 @@ field is a structure then it is a recursive call. When the reference count for a field becomes 0 the field is deleted. Note than user code should never call decReferenceCount since the destructor for PVField calls it.

-

PVData data objects

+

PVData data objects

All PVData data objects must publically extend PVField, which does not allow default methods but does have a virtual destructor. It is expected that each @@ -2098,7 +2306,7 @@ After deletion all pointers to data in the record are invalid. Similarly pvAccess creates and destroys PVData objects and notifies clients before destroying PVData data objects.

-

Other code in this project

+

Other code in this project

The classes in property, i.e. alarm, timeStamp, display, and control are all meant to be free copied and shared. They can be created on the stack. In most @@ -2109,10 +2317,10 @@ be extended. Thus they can only be created via "new" and must be destroyed via "delete".

-

Examples

+

Examples

-

Accessing PVData

+

Accessing PVData

Assume that code wants to print two fields from a PVStructure:

@@ -2140,7 +2348,7 @@ be extended. Thus they can only be created via "new" and must be destroyed via timeStampPV->toString(buf); } -

Creating PVData

+

Creating PVData

Example of creating a scalar field.

    PVDataCreate *pvDataCreate = getPVDataCreate();
@@ -2170,10 +2378,10 @@ and a timeStamp and alarm. Do it the easy way.

         String("timeStamp,alarm"))
-

Property

+

Property

-

Definition of Property

+

Definition of Property

Only fields named "value" have properties. A record can have multiple value fields, which can appear in the top level structure of a record or in a @@ -2213,7 +2421,7 @@ structure powerSupplySimple powerSupplyValueStructure power powerSupplyValueStructure current -

Standard Properties

+

Standard Properties

The following field names have special meaning, i.e. support properties for general purpose clients.

@@ -2281,7 +2489,7 @@ examples are:

that support the PVData data model. For example a powerSupport record can have fields power, voltage, current that each support the PVData data model.

-

Overview of Property Support

+

Overview of Property Support

Except for enumerated, each property has two files: a property.h and a pvProperty.h . For example: timeStamp.h @@ -2310,7 +2518,7 @@ stack. For example the following is permitted:

... } -

timeStamp

+

timeStamp

A timeStamp is represented by the following structure

structure timeStamp
@@ -2336,7 +2544,7 @@ that can be attached to a time stamp pvData structure. It provides get and set
 methods to get/set a TimeStamp as defined by timeStamp.h

 
-
timeStamp.h

+
timeStamp.h

 
 
This provides 

 
extern int32 milliSecPerSec;
@@ -2438,7 +2646,7 @@ execute. This is done as follows:

     endTime.getCurrent();
     double time = TimeStamp::diff(endTime,startTime);

 
-
pvTimeStamp.h

+
pvTimeStamp.h

 
class PVTimeStamp {
 public:
     PVTimeStamp();
@@ -2477,7 +2685,7 @@ public:
       thrown if not attached to a pvData structure.
-

alarm

+

alarm

An alarm structure is defined as follows:

structure alarm
@@ -2499,7 +2707,7 @@ style="font-family: courier;">pvAlarm.h is a class that can be attached
 to a time stamp pvData structure. It provides get and set methods to get/set a
 Alarm as defined by alarm.h

 
-
alarm.h

+
alarm.h

 
enum AlarmSeverity {
  noAlarm,minorAlarm,majorAlarm,invalidAlarm
 };
@@ -2545,7 +2753,7 @@ public:
     
Set the severity.

 
 
-
pvAlarm.h

+
pvAlarm.h

 
class PVAlarm {
 public:
     PVAlarm() : pvSeverity(0),pvMessage(0) {}
@@ -2585,7 +2793,7 @@ public:
       if not attached to a pvData structure. 
 
 
-
control

+
control

 
 
Control information is represented by the following structure

 
structure control
@@ -2603,7 +2811,7 @@ attached to a time stamp pvData structure. It provides get and set methods to
 get/set a Control as defined by control.h

 
-
control.h

+
control.h

 
class Control {
 public:
     Control();
@@ -2628,7 +2836,7 @@ public:
     
Set the high limit.

 
 
-
pvControl.h

+
pvControl.h

 
class PVControl {
 public:
     PVControl();
@@ -2668,7 +2876,7 @@ public:
       thrown if not attached to a pvData structure. 
 
 
-
display

+
display

 
 
Display information is represented by the following structure

 
structure display
@@ -2689,7 +2897,7 @@ class that can be attached to a display pvData structure. It provides get and
 set methods to get/set a Diaplay as defined by diaplay.h

 
-
display.h

+
display.h

 
class Display {
 public:
     Display();
@@ -2732,7 +2940,7 @@ public:
     
Set the units.

 
 
-
pvDisplay.h

+
pvDisplay.h

 
class PVDisplay {
 public:
     PVDisplay()
@@ -2772,7 +2980,7 @@ public:
       thrown if not attached to a pvData structure. 
 
 
-
pvEnumerated

+
pvEnumerated

 
 
An enumerated structure is a structure that has fields:

 
structure
@@ -2839,7 +3047,7 @@ public:
 
 

 
-
PVData Factories

+
PVData Factories

 

 
 
Directory factory has code that implements everything described by the files
@@ -2874,10 +3082,10 @@ the other classes described in pvData.cpp. Each is included and used by
 PVDataCreate.

 

 
-
Miscellanous Classes

+
Miscellanous Classes

 

 
-
Overview

+
Overview

 
 
This package provides utility code:

 

@@ -2925,7 +3133,7 @@ PVDataCreate.

 
Note that directory testApp/misc has test code for all the classes in misc.
 The test code also can be used as examples.

 
-
BitSet

+
BitSet

 
 
This is adapted from the java.util.BitSet. bitSet.h is:

 
class BitSet /*: public Serializable*/ {
@@ -3019,7 +3227,7 @@ private:
     
Show the current values of the bitSet.

 

 
-
ByteBuffer

+
ByteBuffer

 
 
A ByteBuffer is used to serialize and deserialize primitive data. File
 byteBuffer.h is:

@@ -3059,7 +3267,7 @@ private:
 
 
x

 
-
Event

+
Event

 
 
This class provides coordinates activity between threads. One thread can
 wait for the event and the other signals the event.

@@ -3091,7 +3299,7 @@ private:
     
returns (false,true) if the event is (empty,full)

 
 
-
Exception

+
Exception

 
 
File epicsException.h describes:

 
class BaseException : public std::exception {
@@ -3109,7 +3317,7 @@ private:
 
 
x

 
-
Executor

+
Executor

 
 
An Executor is a thread that can execute commands. The user can request that
 a single command be executed.

@@ -3148,7 +3356,7 @@ execute.

       nothing is done.
 
 
-
Linked List

+
Linked List

 
 
LinkedList implements a double linked list that requires a user to allocate
 the nodes. It is more efficent that std::list. linkedList.h is a template that
@@ -3166,34 +3374,33 @@ class LinkedList;
 template <typename T>
 class LinkedListNode : private LinkedListVoidNode {
 public:
-    LinkedListNode(T *object);
-    ~LinkedListNode();
-    T *getObject();
-    bool isOnList();
+    LinkedListNode(T &object) : LinkedListVoidNode(&object){}
+    ~LinkedListNode() {}
+    T &getObject() { return *static_cast<T *>(LinkedListVoidNode::getObject());}
+    bool isOnList() {return LinkedListVoidNode::isOnList();}
+    friend  class LinkedList<T>;
 };
+
 template <typename T>
 class LinkedList : private LinkedListVoid {
 public:
-    LinkedList();
-    ~LinkedList();
+    LinkedList() : LinkedListVoid() {}
+    ~LinkedList() {}
     int getLength();
-    void addTail(LinkedListNode<T> *node);
-    void addHead(LinkedListNode<T> *node);
-    void insertAfter(LinkedListNode<T> *node,
-        LinkedListNode<T> *addNode);
-    void insertBefore(LinkedListNode<T> *node,
-        LinkedListNode<T> *addNode);
+    void addTail(LinkedListNode<T> &listNode);
+    void addHead(LinkedListNode<T> &listNode);
+    void insertAfter(LinkedListNode<T> &listNode,LinkedListNode<T> &addNode);
+    void insertBefore(LinkedListNode<T> &listNode,LinkedListNode<T> &addNode);
     LinkedListNode<T> *removeTail();
     LinkedListNode<T> *removeHead();
-    void remove(LinkedListNode<T> *listNode);
-    void remove(T *object);
+    void remove(LinkedListNode<T> &listNode);
     LinkedListNode<T> *getHead();
     LinkedListNode<T> *getTail();
-    LinkedListNode<T> *getNext(LinkedListNode<T> *node);
-    LinkedListNode<T> *getPrev(LinkedListNode<T> *node;
+    LinkedListNode<T> *getNext(LinkedListNode<T> &listNode);
+    LinkedListNode<T> *getPrev(LinkedListNode<T> &listNode);
     bool isEmpty();
-    bool contains(T *object);
-};

+};
+

 
 
LinkedListNode has the methods:

 

@@ -3252,34 +3459,30 @@ public:
     
Does the list contain the specified object?

 

 
-
Lock and Mutex

+
Lock and Mutex

 
 
lock.h is:

 
class Mutex  {
 public:
-    Mutex() : id(epicsMutexMustCreate()){}
-    ~Mutex() { epicsMutexDestroy(id) ;}
-    void lock(){epicsMutexMustLock(id);}
-    void unlock(){epicsMutexUnlock(id);}
-private:
-    epicsMutexId id;
+    Mutex();
+    ~Mutex();
+    void lock();
+    void unlock();
 };
 
 
 class Lock : private NoDefaultMethods {
 public:
-    explicit Lock(Mutex *pm)
-    : mutexPtr(pm)
-    {mutexPtr->lock();}
-    ~Lock(){mutexPtr->unlock();}
-private:
-    Mutex *mutexPtr;
+    explicit Lock(Mutex &pm);
+    ~Lock();
+    void lock();
+    void unlock();
+    bool ownsLock() ;
 };

 
-
This is a complete description and definition of lock and mutex. These make
-it easy to have a lock that is as easy to use as Java synchronize. To protect
-some object just create a Mutex for the object and then in any method to be
-synchronized just have code like:

+
Lock is as easy to use as Java synchronize. To protect some object just
+create a Mutex for the object and then in any method to be synchronized just
+have code like:

 
class SomeClass {
 private
     Mutex mutex;
@@ -3289,7 +3492,7 @@ public
  ...
     void method()
     {
-        Lock xx(&mutex);
+        Lock xx(mutex);
         ...
     }

 
@@ -3300,14 +3503,14 @@ the current code block completes.

 once. This can be implemented as follows:

 
    static void init(void) {
         static Mutex mutex;
-        Lock xx(&mutex);
+        Lock xx(mutex);
         if(alreadyInitialized) return;
         // initialization
     }

 
-
Message Queue

+
Message Queue

 
-
Definitions

+
Definitions

 
class MessageNode {
 public:
     String getMessage() const;
@@ -3328,7 +3531,7 @@ public:
     int getClearOverrun();
 };

 
-
MessageQueue

+
MessageQueue

 
 
This is for use by code that wants to handle messages without blocking
 higher priority threads.

@@ -3369,7 +3572,7 @@ higher priority threads.

 
 
Look at miscTest/testMessageQueue.cpp for an example.

 
-
NoDefaultMethods

+
NoDefaultMethods

 
 
If a class privately extends this class then the compiler can not create any
 of the following: default constructor, default copy constructror, or default
@@ -3388,7 +3591,7 @@ assignment contructor.

     NoDefaultMethods & operator=(const NoDefaultMethods &);
     };

 
-
Requester

+
Requester

 
 
A PVField extends Requester. Requester is present so that when database
 errors are found there is someplace to send a message.

@@ -3418,7 +3621,7 @@ public:
     
Gives a message to the requester.

 
 
-
Serialize

+
Serialize

 
 
This is a helper class for serialization, which is required for sending and
 receiving pvData over the nerwork.

@@ -3489,81 +3692,74 @@ properly implemented. 

 
 
x

 
-
Show Constructors and
-Destructors

+
CDRMonitor - Monitor and Report
+Construction and Destruction

 
 
This is a facility that allows a class to report how many objects of that
 class have been created and destroyed. This can help find memory leaks.

-
typedef int64 (*getTotal)();
-
-class ConstructDestructCallback : private NoDefaultMethods {
-public:
-    String getConstructName();
-    int64 getTotalConstruct();
-    int64 getTotalDestruct();
-    int64 getTotalReferenceCount();
-private:
+
struct CDRCount {
+     size_t cons, dtys;
+     long refs;
 };
 
-class ShowConstructDestruct : private NoDefaultMethods {
+class CDRMonitor : private NoDefaultMethods {
 public:
-    static void registerCallback(
-        String name,
-        getTotalFunc construct,
-        getTotalFunc destruct,
-        getTotalFunc reference,
-        deleteStaticFunc deleteFunc);
-    ConstructDestructCallback* getConstructDestructCallback(String name);
-    void constuctDestructTotals(FILE *fd);
-    static void showDeleteStaticExit(FILE *fd);
-private:
+    static CDRMonitor& get();
+    CDRNode* addNode(CDRNode& next);
+    CDRCount current();
+    CDRNode* first();
+    CDRNode* first();
+    void show(FILE*)
+    void show(std::ostream&) const;
+};
+class CDRNode : private NoDefaultMethods {
+public:
+    CDRNode(const String& name);
+    void construct();
+    void destruct(){Lock x(guard);
+     void incRef();
+    void decRef();
+    CDRNode* next();
+     CDRCount get();
+    void show(FILE*);
+    void show(std::ostream&);
 };
 
-extern ShowConstructDestruct* getShowConstructDestruct();

+static inline CDRNode* getNode(CDRNodeInstance *inst);
+

 
-
ConstructDestructCallback is implemented by ShowConstructDestruct. MARTY
-EDIT how many instances of the class has been created and how many destroyed.
-The clas must implement this class and register it with ShowConstructDestruct.
-To see an example of how this is implemented look at misc/thread.cpp.

+
Status

 
-
The public methods of ConstructDestructCallback are:

-

-  
getConstructName

-    
Get the name for the facility keeping track of constructor and
-      destructor calls.

-  
getTotalConstruct

-    
Get the total number of objects created.

-  
getTotalDestruct

-    
Get the total number of objects destroyed.

-  
getTotalReferenceCount

-    
For reference counted objects get the total number of current
-      references.

-

-
-
The public methods of ShowConstructDestruct are:

-

-  
registerCallback

-    
Called by code that implements keeping track of constructor and
-      destructor calls. Any of the methods can be null.

-  
getConstructDestructCallback

-    
Given the name of a facility get it's ConstructDestructCallback. This
-      returns null if no facility with that name is registered.

-  
constuctDestructTotals

-    
Generate a report showing the status of each registered facility.

-  
showDeleteStaticExit

-    
Generate a report showing the status of each registered facility. Then
-      call the deleteFunc method of each facility. The delete method normally
-      deletes and object created at initializatuon time. NOTE THAT THIS IS
-      DANGEROUS. It is provided so the test code can be run under a facility,
-      like valgrind, that looks for memory leaks. THIS MUST ONLY BE CALLED
-      IMMEDIATELY BEFORE TERMINATION.

-

-
-
Status

-
-
Status provides a way to pass status back to client code. It is new and not
-currently used by pvData but may be in the future. It is used by code that uses
-pvData.

+
Status provides a way to pass status back to client code:

+
class Status : public epics::pvData::Serializable {
+    public:
+   enum StatusType { 
+         /** Operation completed successfully. */
+         STATUSTYPE_OK,
+         /** Operation completed successfully, but there is a warning message. */
+         STATUSTYPE_WARNING,
+         /** Operation failed due to an error. */
+         STATUSTYPE_ERROR,
+         /** Operation failed due to an unexpected error. */
+         STATUSTYPE_FATAL
+    }; 
+    static const char* StatusTypeName[];
+    static Status OK;
+    Status();
+    Status(StatusType type, epics::pvData::String message);
+    Status(StatusType type, epics::pvData::String message, epics::pvData::String stackDump);
+    ~Status()
+    StatusType getType() const;
+    String getMessage() const;
+    String getStackDump() const;
+    bool isOK() const;
+    bool isSuccess() const;
+    String toString() const;
+    void toString(StringBuilder buffer, int indentLevel = 0) const;
+    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
+    void serialize(ByteBuffer *buffer, SerializableControl *flusher) const;
+};
+

 
 
The Status methods are:

 

@@ -3589,9 +3785,9 @@ pvData.

       status optimization.
 

 
-
Thread

+
Thread

 
-
ThreadPriority

+
ThreadPriority

 
enum ThreadPriority {
     lowestPriority,
     lowerPriority,
@@ -3608,7 +3804,7 @@ public:
     static int getEpicsPriority(ThreadPriority threadPriority);
 };

 
-
Thread

+
Thread

 
class Runnable {
 public:
     virtual void run() = 0;
@@ -3655,7 +3851,7 @@ exception is thrown if run remains active when delete is called. 

     
Make the current thread sleep for the specified number of seconds.

 
 
-
Time Function Call

+
Time Function Call

 
 
TimeFunction is a facility that measures the average number of seconds a
 function call requires. When timeCall is called, it calls function in a loop.
@@ -3697,7 +3893,7 @@ long a function takes. It has the single method:

       one second to call it ntimes.
 
 
-
Timer

+
Timer

 
 
This provides a general purpose timer. It allows a user callback to be
 called after a delay or periodically. 

@@ -3720,8 +3916,8 @@ class Timer : private NoDefaultMethods {
 public:
     Timer(String threadName, ThreadPriority priority);
     ~Timer();
-    void scheduleAfterDelay(TimerNode *timerNode,double delay);
-    void schedulePeriodic(TimerNode *timerNode,double delay,double period);
+    void scheduleAfterDelay(TimerNode &timerNode,double delay);
+    void schedulePeriodic(TimerNode &timerNode,double delay,double period);
 private:
 };

 
@@ -3772,7 +3968,7 @@ be used to schedule multiple callbacks. It has the methods:

     
Schedule a periodic callback.

 
 
-
Queue

+
Queue

 
 
This provides a queue which has an immutable capacity. When the queue is
 full the user code is expected to keep using the current element until a new
@@ -3853,11 +4049,10 @@ public:
          queue->releaseUsed(element);
      }

 

-
-
pvMisc

+
pvMisc

 

 
-
BitSetUtil

+
BitSetUtil

 
 
The following is also provided:

 
class BitSetUtil : private NoDefaultMethods {
@@ -3886,7 +4081,7 @@ currently has only one method:

       entire structures if the structure offset bit is set. 
 
 
-
MultiChoice

+
MultiChoice

 
 
MultiChoice defines an array of strings and a bit set that selects an
 arbitrary set of the choices. This will be implemented if the java version is
@@ -3894,7 +4089,7 @@ accepted.

 
NOT DONE

 

 
-
License Agreement

+
License Agreement

 

 
Copyright (c) 2008 Martin R. Kraimer
 Copyright (c) 2007 Control System Laboratory,