/[ascend]/trunk/base/generic/solver/mtx_use_only.h
ViewVC logotype

Contents of /trunk/base/generic/solver/mtx_use_only.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 994 - (show annotations) (download) (as text)
Fri Dec 22 14:28:40 2006 UTC (15 years, 9 months ago) by johnpye
File MIME type: text/x-chdr
File size: 27924 byte(s)
Added VAR_DIFF and VAR_DERIV flags to var_variable type.
Added flagging of variables as such during integrator_analyse_dae.
Cleaned out some old guff from the mtx* headers.
1 #ifdef __MTX_C_SEEN__
2 /*
3 * mtx2: Ascend Sparse Matrix Package
4 * by Benjamin Andrew Allan
5 * Derived from mtx by Karl Michael Westerberg
6 * Created: 5/3/90
7 * Version: $Revision: 1.9 $
8 * Version control file: $RCSfile: mtx_use_only.h,v $
9 * Date last modified: $Date: 2000/01/25 02:27:13 $
10 * Last modified by: $Author: ballan $
11 *
12 * This file is part of the SLV solver.
13 *
14 * Copyright (C) 1996 Benjamin Andrew Allan
15 * based (loosely) on mtx
16 * Copyright (C) 1990 Karl Michael Westerberg
17 * Copyright (C) 1993 Joseph Zaher
18 * Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan
19 * Copyright (C) 1995 Kirk Andre Abbott, Benjamin Andrew Allan
20 *
21 * The SLV solver is free software; you can redistribute
22 * it and/or modify it under the terms of the GNU General Public License as
23 * published by the Free Software Foundation; either version 2 of the
24 * License, or (at your option) any later version.
25 *
26 * The SLV solver is distributed in hope that it will be
27 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
28 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
29 * General Public License for more details.
30 *
31 * You should have received a copy of the GNU General Public License along with
32 * the program; if not, write to the Free Software Foundation, Inc., 675
33 * Mass Ave, Cambridge, MA 02139 USA. Check the file named COPYING.
34 * COPYING is found in ../compiler.
35 */
36
37 /** @file
38 * mtx2: Ascend Sparse Matrix Package (Private).
39 *
40 * This file defines the private parts of an mtx and is only for mtx*.c
41 * consumption. Any temptation to include this header in a linear or
42 * nonlinear solver package is a symptom of extremely bad programming
43 * and lack of proper task analysis. This header should be regarded as
44 * highly unstable. We make ABSOLUTELY NO commitment to maintain
45 * consistency between any two versions of this file.<br><br>
46 *
47 * Note to third parties:
48 * mtx is PRODUCTION code in very long use at Carnegie Mellon University.
49 * * As such, we maintain a very tight hold of the internals of our data
50 * structure so that we can easily prove the code when apparent bugs arise.
51 * 99.44% of "bugs" experienced in using mtx are the result of not
52 * reading the public headers carefully.<br><br>
53 *
54 * The material in this file was never a part of any header until the
55 * old mtx.c file got so big that we had to split it up to make it
56 * manageable.<br><br>
57 *
58 * Note to future developers of the mtx module. If you change ANYTHING
59 * in this file it is YOUR job to:
60 * a) clear that change with all the other developers using this header
61 * b) fix ALL the other mtx*.c files that depend on it.
62 * If you are not willing to do that much work, why the hell are you
63 * dabbling in sparse matrix math? go work on GUIs.
64 * <pre>
65 * requires: #include <stdio.h>
66 * requires: #include "utilities/ascConfig.h"
67 * requires: #include "mem.h"
68 * requires: #include "mtx.h"
69 * <pre>
70 */
71
72 #ifndef __MTX_INTERNAL_USE_ONLY_H__
73 #define __MTX_INTERNAL_USE_ONLY_H__
74
75 #ifndef FALSE
76 /** These should have come in from ascConfig.h.
77 * @todo Remove redefines of FALSE & TRUE to enforce pre-inclusion of ascCenfig.h? */
78 #define FALSE 0
79 #define TRUE 1
80 #endif
81
82 #define MTX_DEBUG FALSE
83 /**< MTX_DEBUG is a no holds barred sanity checking flag for use when
84 * nothing else is giving a clue why something is going wrong. It
85 * slows down the code to a crawl. Do not under any conditions change
86 * its value or undefine it except at this location. If you need some
87 * other sort of debugging flag for debugging a particular function,
88 * use some personal debugging flag.
89 */
90
91 #define EVEN FALSE
92 #define ODD TRUE
93 #define SWAPS_PRESERVE_ORDER TRUE
94 /**<
95 *** Do row and column swaps preserve the ordering of non-zeros in rows
96 *** and columns? Setting this to TRUE means swapping only entails the
97 *** movement of integer row or column numbers and NOT the exchange of
98 *** entire row or columns.
99 **/
100 #define WIDTHMAGIC 2048
101 /**<
102 *** WIDTHMAGIC is the byte size to aim for in allocating groups of elements.
103 **/
104 #define LENMAGIC 10
105 /**<
106 *** LENMAGIC initial # of groups of elements, hence the smallest
107 *** possible number of elements a matrix will ever have is LENM*WIDTHM/eltsize.
108 **/
109
110 extern FILE *g_mtxerr;
111 /**<
112 *** Global file pointer to which errors are reported. Should never be
113 *** NULL. Also useful when running ascend in gdb and you can't find
114 *** any other file pointer to use.
115 **/
116
117 /** just a struct to make resulting code more readable. */
118 struct next_element_t {
119 struct element_t *row;
120 struct element_t *col;
121 };
122
123 /**
124 *** This is the basic jacobian element of an mtx.
125 *** It's size is 24 bytes on 4 byte pointer machines and
126 *** 32 bytes on 8 byte pointer machines.
127 *** The elements form a bidirectional singly linked list.
128 *** The row and col indices in an element refer back to
129 *** the header positions of the two lists that element is in.
130 *** That is, each element knows its orgrow and orgcol.
131 **/
132 struct element_t {
133 real64 value;
134 int32 row;
135 int32 col;
136 struct next_element_t next;
137 };
138
139 /**
140 *** Each matrix is really just a pair of arrays of pointers to
141 *** elements. The index of a row or column in THESE arrays is
142 *** what is referred to as an org index. A value of NULL in
143 *** either array means that that row (or col) is empty.<br><br>
144 ***
145 *** When we insert elements in the matrix, we simply shove the
146 *** element in at the head of the its row/column lists.
147 *** When we delete an element in the matrix, we search in one
148 *** direction and unlink the element, marking it "dead". Then a
149 *** general pass in the other direction unlinks all the "dead"
150 *** elements.<br><br>
151 ***
152 *** Special note: The -1th element of nz_header arrays is NOT allocated.
153 **/
154 struct nz_headers_t {
155 struct element_t **row;
156 struct element_t **col;
157 };
158
159 /**<
160 *** We maintain, rather than rederiving, the information required to
161 *** answer all possible permutation questions.
162 *** This is a policy decision based on the fact that mtx is research
163 *** code that needs maximal flexibility at reasonable speed.<br><br>
164 ***
165 *** The -1th element of org_to_cur and cur_to_org are defined because
166 *** -1 is used all over mtx as an error return. It's easier to debug
167 *** things without the memory access errors that would happen if
168 *** -1 were not allocated or were part of memory in some other object.<br><br>
169 ***
170 *** Special note: The -1th element of nz_header arrays is NOT allocated.<br><br>
171 ***
172 *** Do not access the parity field of a slave matrix, refer to its master.
173 *** Conduct all permuting operations on the master.
174 **/
175 struct permutation_t {
176 int32 *org_to_cur; /**< org_to_cur[-1] = -1 */
177 int32 *cur_to_org; /**< cur_to_org[-1] = -1 */
178 boolean parity;
179 };
180
181 struct permutations_t {
182 struct permutation_t row;
183 struct permutation_t col;
184 int32 transpose;
185 };
186
187 /**<
188 *** There is a list of blocks associated with a matrix.
189 *** This is an artifact of POOR solver API design between
190 *** Peter Piela and Karl Westerberg. The blockwise decomposition
191 *** information properly belongs to a linear or nonlinear solver
192 *** and not to the mtx.
193 ***
194 *** @todo We intend to fix this soon.
195 **/
196 struct structural_data_t {
197 int32 symbolic_rank; /**< Symbolic rank (< 0 if invalid) */
198 int32 nblocks; /**< # blocks in matrix */
199 mtx_region_t *block; /**< Pointer to array of blocks */
200 };
201
202 /**<
203 *** capacity may be > order.
204 *** A matrix of capacity 0 doesn't have a mem_store_t yet and elements
205 *** cannot be queried about without a core dump.
206 **/
207 struct mtx_header {
208 int integrity; /**< Integrity integer */
209 int32 order; /**< Order of the matrix */
210 int32 capacity; /**< Capacity of all the arrays */
211 int32 nslaves; /**< number of slave matrices */
212 struct nz_headers_t hdr; /**< Non-zero headers of the matrix */
213 struct element_t *last_value; /**< value/set_value memory */
214 mem_store_t ms; /**< element cache memory */
215 struct permutations_t perm; /**< Permutation vectors */
216 struct structural_data_t *data; /**< Pointer to structural information */
217 mtx_matrix_t master; /**< the master of this mtx, if slave */
218 mtx_matrix_t *slaves; /**< array of slave matrices */
219 };
220
221 /**<
222 *** If you want to save a permutation for restoration, you
223 *** have to make a copy of that data, eh? Here's the place you
224 *** put it. Note that the block list should be disappearing from
225 *** from the structural data soon.
226 **/
227 struct mtx_block_perm_structure {
228 int integrity;
229 int32 order; /**< Order of the matrix */
230 int32 capacity; /**< Capacity of all the arrays */
231 mtx_matrix_t mtx; /**< matrix of origin */
232 struct permutations_t perm; /**< Permutation vectors */
233 struct structural_data_t *data; /**< Pointers to structural information */
234 };
235
236 #define OK ((int)201539237)
237 /**< Matrix integrity (ok) value. */
238 #define DESTROYED ((int)531503871)
239 /**< matrix integrity (destroyed) value. */
240
241 #define ZERO ((int32)0)
242 #define D_ZERO ((real64)0.0)
243 #define D_ONE ((real64)1.0)
244 /**< useful constants if your C compiler is not too bright about ANSI */
245
246 #define ISSLAVE(m) ((m)->master!=NULL)
247 /**< Returns 1 if m is a slave matrix, 0 if not. */
248
249 #define ordered3(a,b,c) ((a) <= (b) && (b) <= (c))
250 #define in_range(rng,ndx) ordered3((rng)->low,ndx,(rng)->high)
251 #define legal(mtx,ndx) ordered3(ZERO,ndx,(mtx)->order-1)
252 /**<
253 *** Boolean operators to compare a row or column
254 *** index with some specified range or the maximum
255 *** range of the matrix in which it is used.
256 **/
257
258 #define fast_in_range(l,h,i) ( ordered3(l,i,h) )
259 #define not_in_range(l,h,i) ( (i)<(l) || (i)>(h) )
260 /**<
261 *** Boolean operators to compare 3 integers.
262 *** l <= h must be TRUE or these will lie. In many cases,
263 *** this condition can (or should) be met before in_range
264 *** is called. Sometimes these are not faster since the lo,hi vals cost.
265 *** In particular, queries like next_col do not profit while calls
266 *** which must traverse an entire row/col do.
267 *** Gains in cycle count on dec alphas+cc are about 10% per function,
268 *** but the gains in time are more like 1%, so alpha pixie is lying a little.
269 *** For compilers which are not as clever as Decs, (gcc, sun acc) the
270 *** gains should be much more visible. (some do not realize rng->low
271 *** is invariant even with -O.)
272 *** Note that these are 'loose' comparisons if !(l<=h)
273 **/
274
275 #define zero(ptr,nelts,type) \
276 mem_zero_byte_cast((ptr),0,(nelts)*sizeof(type))
277 /**<
278 *** Zeros a vector of specified length and type.
279 *** It is inefficient to use, however, if you know the type
280 *** is one of the basic types (int,double,ptr,char)
281 **/
282
283
284 /* ************************************************************************ *\
285 Private check routines
286 \* ************************************************************************ */
287 extern int super_check_matrix(mtx_matrix_t mtx);
288 /**<
289 *** After somevery extensive checking, returns an error count.
290 *** More or less assume MTX_DEBUG is TRUE, and that is the only
291 *** condition under which this should be called.
292 **/
293
294 /* ************************************************************************ *\
295 Element CREATE/find routines. Please try to confine use of these to
296 mtx_basic.c as much as possible.
297 Use of find should be avoided at all costs, and in particular
298 absolutely noone outside mtx should put their fingers on elements.
299
300 These functions are not exported to generic users because they are
301 on the critical path and we cannot afford the sanity checking required.
302 They should only be called in contexts where the arguments are
303 guaranteed valid.
304 \* ************************************************************************ */
305
306 struct element_t *mtx_find_element(mtx_matrix_t mtx,
307 int32 org_row,
308 int32 org_col);
309 /**<
310 *** Searches for a given element of the matrix and returns a pointer to it
311 *** if it exists, or NULL if it doesn't exist.
312 *** It is *ASSUMED* that org_row
313 *** and org_col are legal indices. May crash if they are not.
314 **/
315
316 struct element_t *mtx_create_element(mtx_matrix_t mtx,
317 int32 org_row,
318 int32 org_col);
319 /**<
320 *** Creates the given element and returns a pointer to it. The value is
321 *** initially zero.
322 *** It is *ASSUMED* that org_row
323 *** and org_col are legal indices. May crash if they are not.
324 *** If mtx_DEBUG is TRUE, then we will whine if the element already
325 *** exists, but go ahead and create it anyway.
326 **/
327
328 struct element_t *mtx_create_element_value(mtx_matrix_t mtx,
329 int32 org_row,
330 int32 org_col,
331 real64 val);
332 /**<
333 *** Creates the given element and returns a pointer to it. The value is
334 *** initialzed to val.
335 *** It is *ASSUMED* that org_row
336 *** and org_col are legal indices. May crash if they are not.
337 *** If mtx_DEBUG is TRUE, then we will whine if the element already
338 *** exists, but go ahead and create it anyway.
339 **/
340
341 /* ************************************************************************ *\
342 Element list traversals. No linear algebra programmer with an ounce of
343 intelligence would ever need to use these in critical path functions.
344 \* ************************************************************************ */
345 extern struct element_t *mtx_next_col(register struct element_t *elt,
346 mtx_range_t *rng,
347 int32 *tocur);
348 /**<
349 *** Returns the next element after elt that is in the range
350 *** rng according to the permutation vector tocur given. May return NULL.
351 **/
352
353 extern struct element_t *mtx_next_row(register struct element_t *elt,
354 mtx_range_t *rng,
355 int32 *tocur);
356 /**<
357 *** Returns the next element after elt that is in the range
358 *** rng according to the permutation vector tocur given. May return NULL.
359 **/
360
361 /* ************************************************************************ *\
362 Permutation memory management.
363 \* ************************************************************************ */
364 extern int32 *mtx_alloc_perm(int32 cap);
365 /**<
366 *** Allocates a permutation vector. The user need
367 *** not concern himself with the -1st element, which does exist.
368 **/
369
370 extern void mtx_copy_perm(int32 *tarperm, int32 *srcperm, int32 cap);
371 /**<
372 *** Copies srcperm to tarperm given the capacity of srcperm.
373 *** If tarperm was obtained from alloc_perm(), the -1 has already been copied.
374 **/
375
376 extern void mtx_free_perm(int32 *perm);
377 /**<
378 *** Frees resources used by a permutation vector.
379 **/
380
381 /* ************************************************************************ *\
382 It is advantageous in an interactive system to introduce reusable
383 memory and monitor its integrity rather than to repeatedly allocate
384 and zero it. The following code accomplishes this for mtx.
385 A null_vector is an array of objects (size s, length n) with value 0.
386 This sort of memory management is needed because there is always the chance
387 that a floating point exception could cause premature return of an mtx
388 client. This way we have a safe place to store pointers to the memory
389 even if the user's algorithm loses them.
390 \* ************************************************************************ */
391
392 struct reusable_data_vector {
393 void *arr; /**< pointer to array of objects size entrysize */
394 int capacity; /**< number of object slots in array */
395 size_t entry_size; /**< size of slots */
396 int last_line; /**< line most recently associated with this structure,
397 should be 0 if the array is not in use. */
398 };
399
400 extern struct reusable_data_vector
401 g_mtx_null_index_data, /**< bunch of int32 */
402 g_mtx_null_sum_data, /**< bunch of mtx_value_t */
403 g_mtx_null_mark_data, /**< bunch of char */
404 g_mtx_null_vector_data, /**< bunch of element pointers */
405 g_mtx_null_col_vector_data, /**< bunch of element pointers */
406 g_mtx_null_row_vector_data; /**< bunch of element pointers */
407
408 /* OLD GROUP COMMENTS */
409 /*
410 *** vec = mtx_null_vector(nptrs);
411 *** vec = mtx_null_col_vector(nptrs);
412 *** vec = mtx_null_row_vector(nptrs);
413 *** marks = mtx_null_mark(nchar);
414 *** sums = mtx_null_sum(nnums);
415 *** indexes = mtx_null_index(ninds);
416 ***
417 *** struct element_t **vec;
418 *** char *marks;
419 *** real64 *sums;
420 *** int32 *indexes;
421 *** int32 nptrs, nchar, nnums, ninds;
422 ***
423 *** Returns an array of chars, elt pointers, indexes or numbers all NULL/0.
424 *** We need these a lot, but seldom simultaneously, and we know generally
425 *** how to rezero them when done with them.
426 *** These functions should not be
427 *** called again until the vector is re-NULLED and out of use.
428 *** If we detect a double call, we will whine loudly, renull
429 *** the array ourselves, and give it to you again.
430 *** To avoid whining, call the corresponding release functions
431 *** each time you are done with one of these vectors.
432 ***
433 *** In the event of insufficient memory (alloc failed) we will
434 *** return NULL. If we return NULL, you needn't call the release function.
435 ***
436 *** mtx_null_vector_release();
437 *** mtx_null_col_vector_release();
438 *** mtx_null_row_vector_release();
439 *** mtx_null_mark_release();
440 *** mtx_null_sum_release();
441 *** mtx_null_index_release();
442 ***
443 *** These are a memory reuse promoter.
444 *** Calling with cap==0 frees any memory in use.
445 *** Clientlists -- PLEASE KEEP THIS UP TO DATE --
446 *** mtx_null_vector:
447 *** expand_row,expand_col, mtx_assemble
448 *** mtx_householder_transform
449 *** mtx_null_row_vector:
450 *** expand_row_series
451 *** mtx_null_col_vector:
452 *** expand_col_series
453 *** mtx_null_mark:
454 *** mtx_householder_transform
455 *** mtx_null_sum:
456 *** mtx_householder_transform
457 *** mtx_null_index:
458 *** mtx_householder_transform
459 **/
460 #define mtx_null_vector(cap) \
461 ((struct element_t **)mtx_null_vector_f(cap,__LINE__,__FILE__, \
462 &g_mtx_null_vector_data,"null_vector"))
463 /**<
464 * Returns an array of elt pointers all NULL/0.
465 * This function should not be called again until the vector is
466 * re-NULLED and out of use. If we detect a double call, we will
467 * whine loudly, renull the array ourselves, and give it to you again.
468 * To avoid whining, call mtx_null_vector_release()
469 * each time you are done with the returned vector.<br><br>
470 *
471 * In the event of insufficient memory (alloc failed) we will
472 * return NULL. If we return NULL, you needn't call the release function.
473 * @param cap int32, the capacity of the matrix (0 to free memory).
474 * @return No return value.
475 * @see mtx_null_vector_f()
476 */
477 #define mtx_null_row_vector(cap) \
478 ((struct element_t **)mtx_null_vector_f(cap,__LINE__,__FILE__, \
479 &g_mtx_null_row_vector_data,\
480 "null_row_vector"))
481 /**<
482 * Returns an array of elt pointers all NULL/0.
483 * See mtx_null_vector() for more details.
484 * @param cap int32, the capacity of the matrix (0 to free memory).
485 * @return No return value.
486 * @see mtx_null_vector_f()
487 */
488 #define mtx_null_col_vector(cap) \
489 ((struct element_t **)mtx_null_vector_f(cap,__LINE__,__FILE__, \
490 &g_mtx_null_col_vector_data,\
491 "null_col_vector"))
492 /**<
493 * Returns an array of elt pointers all NULL/0.
494 * See mtx_null_vector() for more details.
495 * @param cap int32, the capacity of the matrix (0 to free memory).
496 * @return No return value.
497 * @see mtx_null_vector_f()
498 */
499 #define mtx_null_mark(cap) \
500 ((char *)mtx_null_vector_f(cap,__LINE__,__FILE__, \
501 &g_mtx_null_mark_data,"null_mark"))
502 /**<
503 * Returns an array of chars all NULL/0.
504 * This function should not be called again until the vector is
505 * re-NULLED and out of use. If we detect a double call, we will
506 * whine loudly, renull the array ourselves, and give it to you again.
507 * To avoid whining, call mtx_null_mark_release()
508 * each time you are done with the returned vector.<br><br>
509 *
510 * In the event of insufficient memory (alloc failed) we will
511 * return NULL. If we return NULL, you needn't call the release function.
512 * @param cap int32, the capacity of the array (0 to free memory).
513 * @return No return value.
514 * @see mtx_null_vector_f()
515 */
516 #define mtx_null_sum(cap) \
517 ((real64 *)mtx_null_vector_f(cap,__LINE__,__FILE__, \
518 &g_mtx_null_sum_data,"null_sum"))
519 /**<
520 * Returns an array of real64 numbers all NULL/0.
521 * This function should not be called again until the vector is
522 * re-NULLED and out of use. If we detect a double call, we will
523 * whine loudly, renull the array ourselves, and give it to you again.
524 * To avoid whining, call mtx_null_sum_release()
525 * each time you are done with the returned array.<br><br>
526 *
527 * In the event of insufficient memory (alloc failed) we will
528 * return NULL. If we return NULL, you needn't call the release function.
529 * @param cap int32, the capacity of the array (0 to free memory).
530 * @return No return value.
531 * @see mtx_null_vector_f()
532 */
533 #define mtx_null_index(cap) \
534 ((int32 *)mtx_null_vector_f(cap,__LINE__,__FILE__, \
535 &g_mtx_null_index_data,"null_index"))
536
537 /**<
538 * Returns an array of int32 indexes all NULL/0.
539 * This function should not be called again until the vector is
540 * re-NULLED and out of use. If we detect a double call, we will
541 * whine loudly, renull the array ourselves, and give it to you again.
542 * To avoid whining, call mtx_null_index_release()
543 * each time you are done with the returned array.<br><br>
544 *
545 * In the event of insufficient memory (alloc failed) we will
546 * return NULL. If we return NULL, you needn't call the release function.
547 * @param cap int32, the capacity of the array (0 to free memory).
548 * @return No return value.
549 * @see mtx_null_vector_f()
550 */
551 #define mtx_null_vector_release() \
552 mtx_null_vector_release_f(__LINE__,__FILE__, \
553 &g_mtx_null_vector_data,"null_vector")
554 /**<
555 * Marks a vector as not in use, or whines if it wasn't.
556 * @param None.
557 * @return No return value.
558 * @see mtx_null_vector_release_f()
559 */
560 #define mtx_null_col_vector_release() \
561 mtx_null_vector_release_f(__LINE__,__FILE__, \
562 &g_mtx_null_col_vector_data,"null_col_vector")
563 /**<
564 * Marks a vector as not in use, or whines if it wasn't.
565 * @param None.
566 * @return No return value.
567 * @see mtx_null_vector_release_f()
568 */
569 #define mtx_null_row_vector_release() \
570 mtx_null_vector_release_f(__LINE__,__FILE__, \
571 &g_mtx_null_row_vector_data,"null_row_vector")
572 /**<
573 * Marks a vector as not in use, or whines if it wasn't.
574 * @param None.
575 * @return No return value.
576 * @see mtx_null_vector_release_f()
577 */
578 #define mtx_null_mark_release() \
579 mtx_null_vector_release_f(__LINE__,__FILE__, \
580 &g_mtx_null_mark_data,"null_mark")
581 /**<
582 * Marks a char array as not in use, or whines if it wasn't.
583 * @param None.
584 * @return No return value.
585 * @see mtx_null_vector_release_f()
586 */
587 #define mtx_null_sum_release() \
588 mtx_null_vector_release_f(__LINE__,__FILE__, \
589 &g_mtx_null_sum_data,"null_sum")
590 /**<
591 * Marks a number array as not in use, or whines if it wasn't.
592 * @param None.
593 * @return No return value.
594 * @see mtx_null_vector_release_f()
595 */
596 #define mtx_null_index_release() \
597 mtx_null_vector_release_f(__LINE__,__FILE__, \
598 &g_mtx_null_index_data,"null_index")
599 /**<
600 * Marks an index array as not in use, or whines if it wasn't.
601 * @param None.
602 * @return No return value.
603 * @see mtx_null_vector_release_f()
604 */
605
606 extern void *mtx_null_vector_f(int32 cap, int line, CONST char *file,
607 struct reusable_data_vector *ptr, char *fn);
608 /**<
609 *** Implementation function for macros generating vectors of NULL
610 *** elements. This includes:
611 *** - mtx_null_vector()
612 *** - mtx_null_col_vector()
613 *** - mtx_null_row_vector()
614 *** - mtx_null_mark()
615 *** - mtx_null_sum()
616 *** - mtx_null_index()
617 ***
618 *** Do not call this function directly - use the appropriate macro
619 *** instead.
620 *** Returns a pointer to cap*ptr->entry_size bytes, which must be cast.
621 *** The memory pointed at is believed to be zero, and will be if the
622 *** user is properly rezeroing the vector before it is released.
623 *** If insufficient memory is available, this whines and returns NULL.
624 *** Calling this with cap==0 causes the reused memory to be deallocated and
625 *** returns NULL.
626 **/
627
628 extern void mtx_null_vector_release_f(int line,
629 CONST char *file,
630 struct reusable_data_vector *ptr,
631 char *fn);
632 /**<
633 *** Implementation function for macros releasing reusable vectors.
634 *** This includes:
635 *** - mtx_null_vector_release()
636 *** - mtx_null_col_vector_release()
637 *** - mtx_null_row_vector_release()
638 *** - mtx_null_mark_release()
639 *** - mtx_null_sum_release()
640 *** - mtx_null_index_release()
641 ***
642 *** Do not call this function directly - use the appropriate macro
643 *** instead.
644 *** Marks a vector as not in use, or whines if it wasn't.
645 *** Does no other checking. Uses line, file and fn in error reporting.
646 **/
647
648 extern void mtx_reset_null_vectors(void);
649 /**<
650 *** This resets the reusable arrays of zeroes to zero in the event
651 *** that they may have been corrupted.
652 **/
653
654 /*
655 * INTERNAL element vector operations of some utility.
656 */
657
658 extern struct element_t **mtx_expand_row(mtx_matrix_t mtx, int32 orgrow);
659 /**<
660 *** Expands the given row into an array of pointers, indexed on original
661 *** col number. The array is obtained from mtx_null_vector().
662 *** Be sure to call mtx_null_vector_release() when done with the vector and
663 *** you have rezeroed it.
664 *** You cannot call this twice without releasing first or call
665 *** mtx_expand_col().
666 **/
667
668 extern struct element_t **mtx_expand_col(mtx_matrix_t mtx, int32 orgcol);
669 /**<
670 *** Expands the given col into an array of pointers, indexed on original
671 *** row number. The array is obtained from mtx_null_vector().
672 *** Be sure to call mtx_null_vector_release() when done with the vector and
673 *** you have rezeroed it.
674 *** You cannot call this twice without releasing first or call
675 *** mtx_expand_row().
676 **/
677
678 extern void mtx_renull_using_row(mtx_matrix_t mtx,
679 int32 orgrow,
680 struct element_t **arr);
681 /**<
682 *** Makes arr NULLed again, assuming that the only non-NULL elements
683 *** must correspond to original col numbers that exist in the given
684 *** orgrow.
685 **/
686
687 extern void mtx_renull_using_col(mtx_matrix_t mtx,
688 int32 orgcol,
689 struct element_t **arr);
690 /**<
691 *** Makes arr NULLed again, assuming that the only non-NULL elements
692 *** must correspond to original row numbers that exist in the given
693 *** orgcol.
694 **/
695
696 extern void mtx_renull_all(mtx_matrix_t mtx, struct element_t **arr);
697 /**<
698 *** Makes arr NULLed again, assuming it is size mtx->order.
699 **/
700
701 #endif /* __MTX_INTERNAL_USE_ONLY_H__ */
702 #endif /* none of your business if you aren't mtx_*.c */
703

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22