As mentioned above, a GDD can describe an n-dimension array. The user @@ -24,9 +24,9 @@ what to do with referenced data.
To manage GDDs in a multi-tasking system or a system that uses many layers of software, GDDs implement reference counting. With -reference counting, only one copy of GDD can be shared by many subsystems. +reference counting, only one instance of a GDD can be shared by many subsystems. The GDD creator function can pass it to many other functions without -worrying about deleting it, when the last function using the GDD requests +worrying about deleting it, only when the last function using the GDD requests that it be destroyed does it really go away.
As menitioned above, a GDD allows the user to describe the data in terms @@ -40,7 +40,7 @@ string and optionally a prototype GDD. The prototype GDD can be a container GDD. The table allows users to retreive GDDs of a specific application type.
-A GDD describe and manages a piece of data using the following information: +A GDD describes and manages a piece of data using the following information:
All GDDs must be created dynamically, a GDD cannot be created on the stack as a local variable. The gdd class forbids the user from deleting -the gdd. In order for referencing counting to work correctly the user must -"unreference" the gdd instance instead of delete it. The gdd class does -take over the memory management routines for itself and all it's subclass. +the gdd. In order for reference counting to work correctly the user must +"unreference" the gdd instance instead of deleting it. The gdd class does +take over the memory management routines for itself and all it's subclasses. This means that you are not using the malloc()/free() memory management when GDDs are created and destroyed. It is important to remember that since reference counting is used, a GDD passed into a function must be referenced @@ -89,7 +89,7 @@ with it.
For a GDD to be useful after it is created, it must be given information to describe the data to will hold. This data was summarized in the overview -section. To further understand and the meaning of all these items and use +section. To further understand the meaning of all these items and use them correctly, each needs to be discussed.
A typical way that application type codes are used is in defining structures. A type code of 54 may be assigned the meaning "Temperature Reading". The -"Temperature Reading" structure may be a container with four GDD in it: +"Temperature Reading" structure may be a container with four GDDs in it: a value, a high alarm limit, a low alarm limit, and units. Each of these GDDs also have an application type code. A generic program can actually be written to completely discover the contents of the @@ -199,7 +199,7 @@ and time stamp. Transfering this type of data in one GDD in fairly easy. If GDDs did not contain time stamps and status, then this actively changing data would need to be transfered as a structure of three GDDs: one for the value, one for the status, and one for the time stamp. In addition -to the three GDDs, a fourth that described the GDD container will need to +to the three GDDs, a fourth that describes the GDD container will need to be transfered.
Bounds, and consequencely a single dimension, in GDD are described by two fields, a start and an element count. With this setup, and n-dimensional space can be described. For example, a typical three dimension array -wouldbe described as a(5,4,6), which is a 5x4x6 cube. In a GDD this +would be described as A(5,4,6), which is a 5x4x6 cube. In a GDD this cube would be described with dimension=3, bounds={(0,5)(0,4)(0,6)}. If we want to describe a subset of this array, we would normally do so by giving two endpoints of the sub-cube, such as (1,2,3)->(2,3,5). In GDD @@ -250,7 +250,7 @@ character array and delete it. The gddDestructor allows reference counting similar to the GDD class. Typically a data array will be associated with one instance of the gddDestructor class. If more then one GDD needs to reference the array, -the each GDD is registered with the same gddDestructor. Each time +then each GDD is registered with the same gddDestructor. Each time the gddDestructor is registered, the reference count should be bumped up. The gddDestructor "run" method will only be invoked when the reference count drops to zero. @@ -277,7 +277,7 @@ Several important issues related to where the actual data is stored must be remembered when using GDDs:
@@ -393,22 +394,23 @@ can be very time consuming. For an array GDD, the bounds and a destructor must be allocated in addition to the GDD itself and referenced into the GDD. For a container GDD, the GDD elements are really stored as a linked list. To access the third element of a container, the linked list must be -traversed. With aitStrings GDD the situation is worse yet. The GDD class -allow for a given GDD to be packed or flattened into a simple linear buffer. +traversed. With aitString GDDs the situation is worse yet. The GDD class +allow for a given GDD to be packed or flattened into a single linear buffer. This mechanism includes packing GDD containers. In the array case, the actual GDD is the first thing in the buffer, followed by any bounds information, followed by the actual data array. The fields of the GDD work exactly as before, except that they reference bounds and data that is in the same buffer. In the case of containers, all the GDDs are stored as an array of GDDs at the front of the buffer, followed by the bounds -information for each of the GDDs, followed by each of the GDDs data array if +information for each of the GDDs, followed by each of the GDD's data arrays if present. There are many advantages of this configuration. Since all the GDDs in a container are stored as an array instead of a linked list, the user can directly index a particular GDD within the container. The -application type table performs with packing on a GDD that is registered +application type table performs this packing on a GDD that is registered as a prototype for a particular type code. Since the GDD for a given type code is now a fixed size, the type code table can manage the GDDs on -a free list. Each type code with a prototype GDD contains a free list +a free list. Each type code database entry with a prototype GDD contains +a free list of GDDs for that type code. Creating a GDD using the type code table involves retrieving a preallocated, packed GDD from a particular free list and giving it to the user. This operation is very fast and efficient since diff --git a/src/gdd/gddref2.html b/src/gdd/gddref2.html index 5db31d9f8..c92b3f5c3 100644 --- a/src/gdd/gddref2.html +++ b/src/gdd/gddref2.html @@ -1,7 +1,8 @@
+gddStatus registerApplicationType(const char* const name, aitUint32& app);
+gddStatus registerApplicationTypeWithProto(const char* const name,
+ gdd* protoDD, aitUint32& app);
+
Register an application type name. The type table will return the
application type code in app that the system has assigned to the name.
The latter function allow a prototype GDD to be registered aloong with
@@ -199,12 +201,14 @@ with the application type name. See User's Guide for more details.
-aitUint32 getApplicationType(const char* const name) const;
-char* getName(aitUint32 app) const;
+
+aitUint32 getApplicationType(const char* const name) const;
+char* getName(aitUint32 app) const;
+
Convert a character string type name to it's integer value. Convert an
integer value to it's character string name.
-gddStatus mapAppToIndex(aitUint32 container_app,
+
gddStatus mapAppToIndex(aitUint32 container_app,
aitUint32 app_to_map, aitUint32& index);
Special function for converting type codes to container GDD array indexes.
The GDD must be a flattened GDD managed by the application type table for
@@ -221,7 +225,7 @@ See User's Guide for details.
-gddStatus smartCopy(gdd* dest, gdd* src);
+
gddStatus smartCopy(gdd* dest, gdd* src);
Given any GDD dest and any GDD src, copy all the data from src to dest
where application type codes match. The src and dest can be any type of
GDD: scalar, array, or container. The src dset do not need to be the
@@ -238,29 +242,31 @@ be in the same order.
-gdd* getDD(aitUint32 app);
+
gdd* getDD(aitUint32 app);
Allocate a GDD for the app and return it. If app has a prototype
registered with it, then the returned gdd will be managed and match the
prototype.
-gddStatus freeDD(gdd* dd);
+
gddStatus freeDD(gdd* dd);
Free any gdd. The method basically just calls unreference on dd. If the
GDD is managed, then it puts it onto a free list for it's application type
code.
-aitUint32 maxAttributes(void) const;
-aitUint32 totalregistered(void) const;
+
+aitUint32 maxAttributes(void) const;
+aitUint32 totalregistered(void) const;
+
Return the total number of names registered in this application type table.
Return the total number of names that can be registered in this application
type table.
-void describe(FILE* fd);
+
void describe(FILE* fd);
Print out "#define" statements for each of the names registered in this
table. Also print out container index labels in the form of #defines. See
User's Guide for details. The file gddApps.h is generated using this
function.
-static gddApplicationTypeTable& AppTable(void);
+
static gddApplicationTypeTable& AppTable(void);
Return the automatically generated application type table for use in a
program.
@@ -270,24 +276,30 @@ destructors to gdd by deriving classes from gddDestructor.
#include "gdd.h"
-gddDestructor(void);
-gddDestructor(void* user_arg);
+
+gddDestructor(void);
+gddDestructor(void* user_arg);
+
Create a gddDestructor, optionally placing an arbitrary pointer in the
destructor which can be referenced when the destructor is actual run.
-gddStatus destroy(void* thing_to_remove);
-virtual void run(void* thing_to_remove);
+
+gddStatus destroy(void* thing_to_remove);
+virtual void run(void* thing_to_remove);
+
The destroy method in invoked by anyone withing to request the destructor
to be run. Destroy invokes the user-written function run when
it's reference count goes to zero. Run should not be invoked
directly by the user. The argument to destroy is the buffer that
needs to be freed by by the destructor. The gdd class invokes destroy
when unreference is called and the gdd's reference count goes to zero. The
-default behavior of run is to cast the buffer thing_to_remove to a
+default behavior of run is to cast the buffer thing_to_remove to a
character array and delete it.
-void reference(void);
-int refCount(void) const;
+
+void reference(void);
+int refCount(void) const;
+
Calling refCount will return the current value in the destructor
reference count. Reference will bump up the reference count of this
destructor.
@@ -299,15 +311,20 @@ A simple class to describe the boundaries of a dimension.
void setSize(aitIndex c);
Sets the number of elements for this bounds.
-void set(aitIndex first, aitIndex cnt);
-void get(aitIndex& first, aitIndex& cnt);
+
+
+void set(aitIndex first, aitIndex cnt);
+void get(aitIndex& first, aitIndex& cnt);
+
Set and get the first element in this bounds and the number of elements.
-aitIndex size(void) const;
+
+
aitIndex size(void) const;
Return the number of element in this bounds.
-aitIndex first(void) const;
+
+
aitIndex first(void) const;
Return the first element in this bounds.
-
#include "gdd.h"
-
#include "gddUtils.h"
-gddSemaphore(void)
-gddSemaphore(gddSemType init)
+
+gddSemaphore(void)
+gddSemaphore(gddSemType init)
+
Create a simple binary gddSemaphore which defaults to full. Create a
-gddSemaphore which
-is set initially to state init. Init is either gddSemEmpty or
-gddSemFull.
+gddSemaphore which is set initially to state init. Init
+is either gddSemEmpty or gddSemFull.
-void give(void)
-void take(void)
+
+void give(void)
+void take(void)
+
Operations for manipulating the semaphore. Take will block if the
semaphore is empty, waiting until it is full. Give sets the
semaphore back to full state.
-int take(aitUint32 usec)
+
int take(aitUint32 usec)
Attempt to perform the semaphore take operation. Only block for usec
microseconds. Returns true if time-out occurred and semaphore is not
really taken.
-
#include "gddUtils.h"
-
#include "aitConvert.h"
-void aitConvert(aitEnum desttype, void* dest, +
void aitConvert(aitEnum desttype, void* dest,
aitEnum srctype, const void* src, aitIndex count)
Take count number of elements from src of type srctype,
copy then to dest and at the same time convert them to type
desttype.
-void aitConvertToNet(aitEnum desttype, void* dest,
- aitEnum srctype, const void* src, aitIndex count)
-void aitConvertFromNet(aitEnum desttype, void* dest,
- aitEnum srctype, const void* src, aitIndex count)
+
+void aitConvertToNet(aitEnum desttype, void* dest,
+ aitEnum srctype, const void* src, aitIndex count)
+void aitConvertFromNet(aitEnum desttype, void* dest,
+ aitEnum srctype, const void* src, aitIndex count)
+
Same as aitConvert but change the byte order or data format to/from
network format. If the local host data format is network data format,
then these function are exactly the same as aitConvert.
-aitLocalNetworkDataFormatSame
+
aitLocalNetworkDataFormatSame
This is a #define which is true if local host byte order is the same
as network byte order, otherwise it is false.
-
#include "aitHelpers.h" -Automatically included if aitTypes.h is included.
+
#include "aitHelpers.h"
+Automatically included if aitTypes.h is included.
-operator double()
-operator float()
+
+operator double()
+operator float()
+
Convert (cast) the seconds/nanoseconds to a double or float seconds with
decimal fraction of a second past epoch.
-static aitTimeStamp getCurrent();
+
static aitTimeStamp getCurrent();
Retrieve the current time in aitTimeStamp format.
-void get(unsigned long &tv_secOut,unsigned long &tv_nsecOut);
+
void get(unsigned long &tv_secOut,unsigned long &tv_nsecOut);
Retreive the various parts of the time stamp as separate quantities.
-aitTimeStamp()
+
aitTimeStamp()
aitTimeStamp(const aitTimeStamp &t)
aitTimeStamp(const unsigned long sec, const unsigned long nsec)
Create an aitTimeStamp that is initially zero or set to various values.
-const unsigned NSecPerSec = 1000000000u;
-const unsigned NSecPerUSec = 1000u;
-const unsigned SecPerMin = 60u;
+
+const unsigned NSecPerSec = 1000000000u;
+const unsigned NSecPerUSec = 1000u;
+const unsigned SecPerMin = 60u;
+
Various constants for working with time.
-
+
aitTimeStamp operator+ (const aitTimeStamp &lhs, const aitTimeStamp &rhs);
aitTimeStamp operator- (const aitTimeStamp &lhs, const aitTimeStamp &rhs);
int operator>= (const aitTimeStamp &lhs, const aitTimeStamp &rhs);
They are global functions for adding and subtracting and comparing time stamps.
-
#include "aitHelpers.h" -Automatically included if aitTypes.h is included.
+
#include "aitHelpers.h"
+Automatically included if aitTypes.h is included.
-aitString(void);
+
aitString(void);
Construct an aitString that is empty.
-
-aitString(char* str);
-aitString(aitString* str);
-aitString(aitString& str);
-
+
+aitString(char* str);
+aitString(aitString* str);
+aitString(aitString& str);
+
Construct an aitString which contains a copy of str. The
state of this aitString will be "allocated".
-
-aitString(const char* str);
-aitString(const aitString* str);
-aitString(const aitString& str);
-
+
+aitString(const char* str);
+aitString(const aitString* str);
+aitString(const aitString& str);
+
Construct an aitString which contains a reference to str. The
state of this aitString will be "constant".
-void clear(void);
+
void clear(void);
Clear out this aitString, freeing up any storage that may be allocated.
-void dump(void) const;
-void dump(const char* id) const;
+
+void dump(void) const;
+void dump(const char* id) const;
+
Print the contents of this aitString to stdout in a readable format. Good
tool for debugging or understanding the aitString class.
-
-operator const char*(void) const;
-operator char*(void) const;
-
+
+operator const char*(void) const;
+operator char*(void) const;
+
Pull out a reference to the string that this aitString is holding. These
are casting operators from aitString to char*.
-int isConstant(void) const;
+
int isConstant(void) const;
Returns true is this aitString hold a constant string.
-
-aitUint32 length(void) const;
-const char* string(void) const;
-
+
+aitUint32 length(void) const;
+const char* string(void) const;
+
Return the length of the string in this aitString. Return a reference to
the string in this aitString.
-
+
aitString& operator=(......);
int copy(......);
-
+
Create a copy of the variable string arguments in this aitString. This
aitString attributes will match that of the arguments. The assignment
operators just invoke copy(......).
-void replaceData(......);
+
void replaceData(......);
Replace the data in this aitString with the string in the argument. This
function will only copy this aitStrings length number of bytes into it's
string from the argument string.
-void installString(......);
+
void installString(......);
Invoke replaceData if this aitString is "constant". Invoke copy if this
aitString is not "constant".
-
+
static aitUint32 totalLength(aitString* array,aitIndex arraySize);
static aitUint32 stringsLength(aitString* array,aitIndex arraySize);
static aitIndex compact(aitString* array, aitIndex arraySize,
- void* buf, aitIndex bufSize);
-
+ void* buf, aitIndex bufSize);
+
totalLength() returns the total number of bytes that an array of aitStrings
requires. This length include the size of all the strings in the aitStrings.
Array is the aitString array, arraySize is the number of
@@ -503,7 +531,7 @@ the front of buf. The aitStrings in buf reference strings that are
further into the buffer buf. Compact returns the total
number of bytes used in buf.
-
+aitTotal
+aitConvertTotal
+aitValid(x)
+aitConvertValid(x)
+
Value of the first two are the number of valid types. All the ait types
cannot be automatically converted using aitConvert. AitValid(x) returns
true if x has a valid ait type enumeration associated with it.
AitConvertValid(x) returns true if enumerated value x can be converted using
aitConvert.
-aitEnum
+
aitEnum
This is an enumerated data type, there is one name per ait types. See
header file for the definition.
-aitType
+
aitType
Data union of all the ait types.
-
-aitSize[aitTotal]
-aitName[aitTotal]
-aitStringType[aitTotal]
-
+
+aitSize[aitTotal]
+aitName[aitTotal]
+aitStringType[aitTotal]
+
Arrays used for discovering information about ait types using the enumerated
ait type name as the index into the array. aitSize returns the size in
bytes of the ait type. aitName returns a character string name of the
ait type. aitStringType returns a string which can be used in sscanf to
read or convert a string into the actual ait type.
-gddStatus - Error Codes
+
#include "gddErrorsCodes.h"
char* gddErrorMessages[]
Return an error message string name for an error code.
-
#include "gddNewDel.h"
A set of generic member function macros that can be added to any class to allow the class to be managed on a free list using the new/delete operators. See the header file for details on how to use this facility. Most GDD library classes use this facility. -
#include "gddApps.h"
This file is generated from the standard application type table. It contains all the #define statements for preregistered containers and application type codes. -
#include "dbMapper.h"
Large set of utility functions for converting between EPICS DBR data types
and GDD containers.
-void gddMakeMapDBR(gddApplicationTypeTable& table);
+
void gddMakeMapDBR(gddApplicationTypeTable& table);
The DBR mapping facility is not initialized automatically. It must be
initialized using this function before any of the functions are called.
It should be passed the standard default
application type table as an argument.
-chtype gddAitToDbr[]
+
chtype gddAitToDbr[]
Given an ait type code, return the equivalent EPICS DBR type code.
-gddDbrToAitTable gddDbrToAit[]
+
gddDbrToAitTable gddDbrToAit[]
Given a DBR type code, return a structure that describe the ait/GDD type code
informtion for that DBR type code. The information in gddDbrToAitTable is
the GDD application type code and GDD application type name for a given DBR
type. This information is not extremely useful for simple applications.
-gddDbrMapFuncTable gddMapDbr[]
+
gddDbrMapFuncTable gddMapDbr[]
Array of conversion functions that convert between DBR structures and GDD
types. The index of this array is always the DBR type code, not the
GDD application type code. Each element of the array contains to functions: