1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
\par
\section{Prototypes and descriptions of {\tt ChvList} methods}
\label{section:ChvList:proto}
\par
This section contains brief descriptions including prototypes
of all methods that belong to the {\tt ChvList} object.
\par
\subsection{Basic methods}
\label{subsection:ChvList:proto:basics}
\par
As usual, there are four basic methods to support object creation,
setting default fields, clearing any allocated data, and free'ing
the object.
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
ChvList * ChvList_new ( void ) ;
\end{verbatim}
\index{ChvList_new@{\tt ChvList\_new()}}
This method simply allocates storage
for the {\tt ChvList} structure
and then sets the default fields by a call to
{\tt ChvList\_setDefaultFields()}.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
void ChvList_setDefaultFields ( ChvList *list ) ;
\end{verbatim}
\index{ChvList_setDefaultFields@{\tt ChvList\_setDefaultFields()}}
The structure's fields are set to default values:
{\tt nlist} and {\tt nlocks} set to zero,
and {\tt heads}, {\tt counts}, {\tt lock} and {\tt flags}
are set to {\tt NULL} .
\par \noindent {\it Error checking:}
If {\tt list} is {\tt NULL},
an error message is printed and the program exits.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
void ChvList_clearData ( ChvList *list ) ;
\end{verbatim}
\index{ChvList_clearData@{\tt ChvList\_clearData()}}
This method clears the object and free's any owned data
by calling {\tt Chv\_free()} for each object on the free
list.
If {\tt heads} is not {\tt NULL}, it is free'd.
If {\tt counts} is not {\tt NULL},
it is free'd via a call to {\tt IVfree()}.
If {\tt flags} is not {\tt NULL},
it is free'd via a call to {\tt CVfree()}.
If the lock is not {\tt NULL}, it is destroyed via a call to
{\tt Lock\_free()}.
There is a concluding call to
{\tt ChvList\_setDefaultFields()}.
\par \noindent {\it Error checking:}
If {\tt list} is {\tt NULL},
an error message is printed and the program exits.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
void ChvList_free ( ChvList *list ) ;
\end{verbatim}
\index{ChvList_free@{\tt ChvList\_free()}}
This method releases any storage by a call to
{\tt ChvList\_clearData()}
and then free the space for {\tt list}.
\par \noindent {\it Error checking:}
If {\tt list} is {\tt NULL},
an error message is printed and the program exits.
%-----------------------------------------------------------------------
\end{enumerate}
\par
\subsection{Initialization methods}
\label{subsection:ChvList:proto:initial}
\par
There are three initializer methods.
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
void ChvList_init( ChvList *list, int nlist, int counts[],
int lockflag, char flags[] ) ;
\end{verbatim}
\index{ChvList_init@{\tt ChvList\_init()}}
Any data is cleared via a call to
{\tt ChvList\_clearData()}.
The number of lists is set and the {\tt heads[]} vector is
initialized.
If {\tt counts} is not {\tt NULL}, the object's {\tt counts[]}
vector is allocated and filled with the incoming entries.
If {\tt lockflag} is zero, the lock is not initialized.
If {\tt lockflag} is {\tt 1}, the lock is initialized
to be able to synchronize threads with the calling process.
If {\tt lockflag} is {\tt 2}, the lock is initialized
to be able to synchronize threads across processes.
If {\tt flags} is not {\tt NULL}, the object's {\tt flags[]}
vector is allocated and filled with the incoming entries.
\par \noindent {\it Error checking:}
If {\tt list} is {\tt NULL},
or if ${\tt nlist} \le 0$,
or if {\tt lockflag} is not in {\tt [0,2]},
an error message is printed and zero is returned.
%-----------------------------------------------------------------------
\end{enumerate}
\par
\subsection{Utility methods}
\label{subsection:ChvList:proto:utility}
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int ChvList_isListNonempty ( ChvList *list, int ilist ) ;
\end{verbatim}
\index{ChvList_isListNonempty@{\tt ChvList\_isListNonempty()}}
\par
If list {\tt ilist} is empty, the method returns 0.
Otherwise, the method returns 1.
\par \noindent {\it Error checking:}
If {\tt list} is {\tt NULL},
or if {\tt ilist} is not in the range {\tt [0,nlist)},
an error message is printed and zero is returned.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
int ChvList_isCountZero ( ChvList *list, int ilist ) ;
\end{verbatim}
\index{ChvList_isCountZero@{\tt ChvList\_isCountZero()}}
\par
If {\tt counts} is {\tt NULL},
or if {\tt counts[ilist]} equal to zero, the method returns 1.
Otherwise, the method returns 0.
\par \noindent {\it Error checking:}
If {\tt list} is {\tt NULL},
or if {\tt ilist} is not in the range {\tt [0,nlist)},
an error message is printed and zero is returned.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
Chv * ChvList_getList ( ChvList *list, int ilist ) ;
\end{verbatim}
\index{ChvList_getList@{\tt ChvList\_getList()}}
\par
If list {\tt ilist} is empty, the method returns {\tt NULL}.
Otherwise, if the list needs to be locked, the lock is locked.
The head of the list is saved to a pointer and then the head is set
to {\tt NULL}.
If the list was locked, the number of locks is incremented and the
lock unlocked.
The saved pointer is returned.
\par \noindent {\it Error checking:}
If {\tt list} is {\tt NULL},
or if {\tt ilist} is not in the range {\tt [0,nlist)},
an error message is printed and zero is returned.
%-----------------------------------------------------------------------
\item
\begin{verbatim}
void ChvList_addObjectToList ( ChvList *list, Chv *chv, int ilist ) ;
\end{verbatim}
\index{ChvList_addObjectToList@{\tt ChvList\_addObjectToList()}}
\par
If the list needs to be locked, the lock is locked.
If {\tt chv} is not {\tt NULL}, it is added to the head of the list.
If {\tt counts} is not {\tt NULL}, then {\tt counts[ilist]} is
decremented.
If the lock was locked, the number of locks is incremented
and it is now unlocked.
\par \noindent {\it Error checking:}
If {\tt list} is {\tt NULL},
or if {\tt ilist} is not in the range {\tt [0,nlist)},
an error message is printed and zero is returned.
%-----------------------------------------------------------------------
\end{enumerate}
\par
\subsection{IO methods}
\label{subsection:ChvList:proto:IO}
\par
%=======================================================================
\begin{enumerate}
%-----------------------------------------------------------------------
\item
\begin{verbatim}
void ChvList_writeForHumanEye ( ChvList *list, FILE *fp ) ;
\end{verbatim}
\index{ChvList_writeForHumanEye@{\tt ChvList\_writeForHumanEye()}}
\par
This method writes the list to a file in user readable form.
\par \noindent {\it Error checking:}
If {\tt list} or {\tt fp} are {\tt NULL},
an error message is printed and zero is returned.
%-----------------------------------------------------------------------
\end{enumerate}
|
