~ubuntu-branches/ubuntu/utopic/gridengine/utopic

<b><font face="Times New Roman, serif">Common Usable List Library<a NAME="sdfootnote1anc" CLASS="sdfootnoteanc" HREF="#sdfootnote1sym"></a><a NAME="sdfootnote1anc" href="#sdfootnote1sym" CLASS="sdfootnoteanc"></a><sup><a href="#sdfootnote1sym" CLASS="sdfootnoteanc" NAME="sdfootnote1anc">1</a></sup></font></b></h1>

<h2>

Capabilities of the Common Usable List Library (CULL)</h2>

The CULL allows to create and maintain so called CULL lists, which are

the central Grid Engine data structure in which almost all Grid Engine

data, such as jobs, queues, hosts, etc., are stored. The CULL has the following

features:

<ul>

<ul>applicability for every client/server in Grid Engine.

<p STYLE="margin-bottom: 0in">reusability of list management code.

<p>no need for recompilation of client code in case of uncritical data

structure changes.

<p>interface duality - either list oriented or SQL inspired.

<p>fast search functions using hash tables</ul>

</ul>

The CULL is the building block for the Grid Engine Database Interface (GDI

- see  <a href="../gdi/gdi.html">here</a>).

<br> 

<h2>

Internal data structures</h2>

See below for a schematic overview of the CULL internal list data structure:

<br> 

<p><br>

<br>

<h3>

lList</h3>

This is the structure for the list header. The meaning of the different

fields is stated in the comments of the structure definition below. The

position and type information for all list elements is maintained in the

lDescr array. The element data itself can be referenced via the first and

last pointers.

<pre>typedef struct {

int nelem; /* number of elements in the list */

char *listname; /* name of the list */

lDescr *descr; /* pointer to the descriptor array */

lListElem *first; /* pointer to the first element of the list */

lListElem *last; /* pointer to the last element of the list */

} lList;</pre>

<h3>

lListElem</h3>

The following structure defines a list element being used to store data

in CULL lists. The data storage occurs in arrays of lMultiType unions (see

below). The access to the data is performed by getting the array index

and the field type through the lDescr struct array. The field descr is

used for type checking.

<pre>typedef struct {

lListElem *next; /* next lList element */

lListElem *prev; /* previous lList element */

lUlong status; /* status: element in list/ element free */

lDescr *descr; /* pointer to the descriptor array */

lMultiType *cont; /* pointer to the lMultiType array */

} lListElem;</pre>

<h3>

lDescr</h3>

The descriptor struct contains two integer fields. One is representing

the name of the field and the other one the associated type. The names

are represented by unique numbers, which can be mapped to enum definitions

or #define statements (the steps to define a list are shown below.)

<pre>typedef struct {

int nm;      /* unique number that stands for a name */

int mt;      /* multitype information */

lHash *hash; /* hashing information */

} lDescr;</pre>

<h3>

lHash</h3>

The lHash structure stores information about hash tables to be used for

100

certain data fields.

101

<br>For each data field that shall be accessed by a hash table, the corresponding

102

descriptor (lDesc) contains a reference to an lHash object. The lHash object

103

defines the type of hash table (unique or non unique keys) and a pointer

104

to a HashTable object.

105

<pre>typedef struct {

106

int unique;      /* 0 = non unique keys, 1 = unique keys */

107

HashTable table; /* pointer to HashTable from libs/uti/sge_hash.* */

108

} lHash;</pre>

109

110

<h3>

111

lMultiType</h3>

112

The lMultiType union consists of various basic types. Which union member

113

has to be accessed is determined by the type field ("mt") in the lDescr

114

struct. An array of lMultiType unions contains the data.

115

<pre>typedef union {

116

lFloat fl; /* float */

117

lDouble db; /* double */

118

lUlong ul; /* unsigned long */

119

lLong l; /* long */

120

lChar c; /* char */

121

lInt i; /* int */

122

lString str; /* char* */

123

lList *glp<b>;</b> /* sublist */

124

lRef ref; /* pointer */

125

lCondition *cp<b>;</b> /* lCondition pointer */

126

} lMultiType;</pre>

127

128

<h2>

129

Usage of the Generic List</h2>

130

In the directory source/lib/cull you can find one example which demonstrates

131

how to use CULL lists. To build it use the aimk script: "aimk example1"

132

<h3>

133

List definition</h3>

134

Each CULL list definition consists of following parts:

135

136

<p STYLE="margin-left: 0.79in">Definition of some constants which identify

137

the attributes of a CULL element.

138

139

<p STYLE="margin-left: 0.79in">A Section which defines the type of the

140

attributes of a CULL element.

141

142

<p STYLE="margin-left: 0.79in">A List of names used when a attribute name

143

should be written in readable form.

144

<p>You can find a definition for a CULL list <a href="hostL.h">here</a>.

145

Lists used in Grid Engine are part of the GDI library. Concerning source

146

code can be found in source/libs/gdi. Each file whose filename ends with

147

an capital L before the .h suffix contains CULL list definitions.

148

<h3>

149

Definition of Name Space</h3>

150

Suppose you intend to write a piece of Grid Engine code based on a new

151

CULL list. One thing you should do is to define the names to be used for

152

the CULL list elements and you have to make sure that none of your names

153

conflicts with already existing names. For this purpose you have to select

154

one or several of the predefined name spaces, which are defined in the

155

header boundaries.h (see <a href="boundaries.h">here</a>). By using one

156

or multiple name spaces, you can create your own list structure as shown

157

below.

158

<p>The file source/libs/gdi/sge_boundaries.h contains the name space definition

159

for Grid Engine.

160

<h3>

161

Application Specific Header File</h3>

162

163

<div STYLE="margin-bottom: 0in">Each attribute within a CULL object is

164

uniquely identified by a constant value which will be used to get or modify

165

its value. For output and debug purpose it is extremely valuable to use

166

strings instead of enum values. Therefore all the list structures that

167

shall be used, should be included in an application specific header file.

168

Here an array of type lNameSpace has to be defined. This table will be

169

used to convert field names to field numbers and vice versa within the

170

CULL library.</div>

171

172

<div STYLE="margin-bottom: 0in">The example1.h file can be found <a href="example1.h">here</a>.

173

The file source/libs/gdi/sge_all_listsL.h containes the array used in Grid

174

Engine.</div>

175

176

<h3>

177

List Usage Example</h3>

178

179

<div STYLE="margin-bottom: 0in">In the the C file <a href="example1.c">example1.c</a>

180

the usage of the various CULL list library functions is explained. Run

181

the corresponding application without any arguments to get a list of scenarios

182

demonstrated by the example.</div>

183

184

<h3>

185

<br>

186

Functional Overview</h3>

187

188

<div STYLE="margin-bottom: 0in">The most important functions of the CULL

189

are explained in the man page <a href="list_intro.txt">list_intro</a>(3).

190

In addition, more high level composite funtions exist, which combine the

191

use of several basic functions for standard tasks. Using these composite

192

functions may reduce the size of the code dramatically. There are no man

193

pages available for the composite functions currently but they are documented

194

in the sourcecode. Here their names are listed:</div>

195

196

<div STYLE="margin-bottom: 0in">lGetElemCaseStr(), lGetElemDescr(), lGetElemHost(),

197

lGetElemIndex(), lGetElemStr(), lGetElemStrLike(), lGetElemUlong(), lGetSubCaseStr(),

198

lGetSubHost(), lGetSubStr(), lGetSubUlong(), lAddElemUlong(), lAddElemStr(),

199

lAddSubStr(), lAddSubUlong(), lDelElemCaseStr(), lDelElemHost(), lDelElemStr(),

200

lDelElemUlong(), lDelSubCaseStr(), lDelSubStr(), lDelSubUlong()</div>

201

202

203

<center><a NAME="sdfootnote1sym" CLASS="sdfootnotesym" HREF="#sdfootnote1anc"></a><a NAME="sdfootnote1sym" href="#sdfootnote1anc" CLASS="sdfootnotesym"></a><a href="#sdfootnote1anc" CLASS="sdfootnotesym" NAME="sdfootnote1sym">1</a>Copyright

204

205

</div>

206

207

</body>

208

</html>

Older »