From 0d2b196be2c91d49174a4a0c134b5b40ccabb3fd Mon Sep 17 00:00:00 2001 From: Jim Kowalkowski Date: Mon, 16 Sep 1996 13:41:29 +0000 Subject: [PATCH] New doc files --- src/gdd/gdd.gif | Bin 0 -> 4417 bytes src/gdd/gdd.html | 169 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 src/gdd/gdd.gif create mode 100644 src/gdd/gdd.html diff --git a/src/gdd/gdd.gif b/src/gdd/gdd.gif new file mode 100644 index 0000000000000000000000000000000000000000..ab12e2e028e4446cf585be5f33b42bf09d8a185b GIT binary patch literal 4417 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 HoB#kjllKmf literal 0 HcmV?d00001 diff --git a/src/gdd/gdd.html b/src/gdd/gdd.html new file mode 100644 index 000000000..55ddf23b4 --- /dev/null +++ b/src/gdd/gdd.html @@ -0,0 +1,169 @@ +GDD User's Guide +

+

General Data Descriptor Library User's Guide

+ +

General Overview

+The purpose of the General Data Descriptor Library (GDD library) is to +fully describe, hold, and manage scalar and array data. Using a GDD, +you can describe a piece of data's type, dimensionality, and structure. +In addition you can identify the data with an integer application type value +which can be translated into a text string. A user can store data into and +retreived data from a GDD in any desired data type. A GDD can contain +a list of GDDs. This allows users to create and describe hierarchical +data structures dynamically. GDD organized in this fashion are known +as containers. +

+As mentioned above, a GDD can describe an n-dimension array. The user +can describe the bounds of the n-dimensional array. To facilitate the +use of large, and perhaps shared data arrays, a GDD allows a user to +store a reference to an array of data. In addition, a destructor function +can be registed in the GDD to inform the owner of the data array when +the GDD referencing the data goes away. The purpose of the destructor +function is to delete the array of data, since the GDD does not know +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. +The GDD creator function can pass it to many other functions without +worrying about deleting it, 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 +of the application. This is done by the user by assigning an arbitrary +integer identifier to a GDD. The user places a meaning on the identifiers +such as 1=high-alarm-limit, 2=low-alarm-limit. This identifier is termed +application type. A second component of the GDD library known as the +Application Type Table is used to manage the application type identifiers. +Application type values are registered in the table along with a text +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: +

+

    +
  • Application Type (user assigned integer value) +
  • Primitive Type (storage type identifier - int/double/short/etc.) +
  • Dimension (of array data) +
  • Bounds (array data structure information) +
  • Destructor (to delete referenced array data) +
  • Time Stamp (last time updated) +
  • Status (user assign data status field) +
  • Reference Count +
  • Data Field +
+ +

+The GDD library is a C++ class library and therefore requires using the +C++ compiler. + +

Creating and Using a GDD

+The gdd class is the main class in the GDD library. It controls almost +all actions perfomed on the data. The gdd class is further broken down +into three subclasses for performing operations are specific types of GDDs: +gddContainer, gddAtomic, and gddScalar. The gddContainer class aids in the +creation of container type GDDs. It adds functions such as "insert GDD", +"remove GDD", and "give me GDD x from the container" to the basic gdd class. +The gddAtomic class helps create and manage array data GDDs. The gddScalar +class makes it easy to create scalar GDDs. +

+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. +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 +before the function returns if the GDD is to be kept for longer then the +running of that function. In other words, if you are creating a library +function "add" that records process variable names in a linked list, and the +process variable names are passed to you as GDDs, then you must reference +the GDD since the linked list exists after the return of the "add" function. +If you are creating a GDD, you must unreference it when you are finished +with it, even it you have passed it into other library functions. +Generalizing on this, it is the responsibility of the GDD creator or +GDD referencer to unreference the GDD instance when they are finished +with it. +

+

Primitive Types

+As mentioned in the overview, a piece of descriptive information that a +GDD maintains is the and primitive type code. This field +describes the format of the data (storage type). +The primitive type field of a GDD is an enumeration +of all the general storage types supported by the compilers. A user can +determine dynamically what the storage format of the data in a GDD is using +the primitive type code information. The GDD library redefines the general +storage class names for integers and floating point numbers and enumerates +them in the "aitTypes.h" header file. The redefined names describe the +format and the bit length so that they can be used across architectures. +The initial part of the header file name "aitTypes.h" is ait which +stands for "Architecture Independant Types". The standard data types +supported by the GDD library are +
+	aitInt8           8 bit character
+	aitUint8          8 bit unsigned character
+	aitInt16          16 bit short
+	aitUint16         16 bit unsigned short
+	aitEnum16         16 enumerated value
+	aitInt32          32 bit integer
+	aitUint32         32 bit unsigned integer
+	aitFloat32        32 bit floating point number
+	aitFloat64        64 bit floating point number
+	aitPointer        Standard pointer
+	aitIndex          32 bit index value
+	aitStatus         32 bit unsigned integer for status value
+	aitFixedString    40 byte string of characters
+	aitString         Variable length string data type
+	aitTimeStamp      Two 32 bit integers describing time (seconds/nanoseconds)
+
+These data types should be used whenever possible to prevent problems when +compiling programs for different architectures. Most of they data types +are enumerated as descrived above for use as a primitive type code. The +enumerated names are just the above type names with the word "Enum" +inserted after "ait". It should be noted that aitTimeStamp is not a +standard primitive type. +
+typedef enum {
+    aitEnumInvalid=0,
+    aitEnumInt8,
+    aitEnumUint8,
+    aitEnumInt16,
+    aitEnumUint16,
+    aitEnumEnum16,
+    aitEnumInt32,
+    aitEnumUint32,
+    aitEnumFloat32,
+    aitEnumFloat64,
+    aitEnumFixedString,
+    aitEnumString,
+    aitEnumContainer
+} aitEnum;
+
+The enumerated type code allows a user to dynamically convert from one +type to another. The AIT portion of the GDD library contains a large +primitive type conversion matrix. The conversion matrix is indexed by +the source and destination enumeration type codes. The matrix is a + +

+Several important issues related to where the actual data is stored +must be remembered when using GDDs: +

    +
  1. If a gdd is a scalar, then the gdd hold the data it describes, the + dimension is zero, and the bounds are empty. +
  2. If a gdd is an array, then the gdd refers to the data it describes, + refers to bounds that describe it's structure, and optionally + refers to a user's data destructor. +
  3. If a gdd is a container, then the dimension is fixed at one and the + bounds describe how many elements are in the container. +
+ +

GDD Reference Manual +

Home page for Jim Kowalkowski.
+ +
Argonne National Laboratory +Copyright +Information
+
jbk@aps.anl.gov (Jim Kowalkowski)
updated 9/13/96
+