Mercurial > cgi-bin > hgwebdir.cgi > VMS > C_Libraries > DynArray

comparison DynArray.h @ 32:958dcb7754ca

find changesets by author, revision, files, or words in the commit message
PR branch -- added comments about safe usage
author Sean Halle <seanhalle@yahoo.com>
date Fri, 08 Mar 2013 05:37:45 -0800
parents e6b21c2350d1
children c6e1805505c9
comparison
equal deleted inserted replaced
14:48eb625d3226 15:dc6e41ce9c58
10 10
11 #include "PR_impl/PR_primitive_data_types.h" 11 #include "PR_impl/PR_primitive_data_types.h"
12 #include "PR_impl/Services_Offered_by_PR/Memory_Handling/vmalloc.h" 12 #include "PR_impl/Services_Offered_by_PR/Memory_Handling/vmalloc.h"
13 13
14 14
15 //A dynamic array is same as any other array, but add a DynArrayInfo next 15
16 // to it. Accesses and updates of array indexes are done normally, it's 16 /*WARNING: Passing a DynArray as a param is dangerous if add to the DynArray
17 // only when add a new element into array that use the extra info. 17 * inside the function called! After adding or other operation that might
18 // An add can cause the pointer to the normal array to change.. so must 18 * change the size, must re-read the addr of the chunk of memory that is the
19 // be protected to single VP at a time. 19 * array, via the DynArrayInfo.
20 *Here's why: An array variable is a location, either on the stack
21 * or in a field of a struct, whose contents is an addr. That addr is of the
22 * first location of a chunk of locations. The DynArray works by changing
23 * the chunk of locations, then modifying the contents of the original
24 * array variable. It overwrites the addr of the old chunk of locations
25 * with the addr of the new chunk.
26 *But when the array variable is passed as a parameter, such as
27 * in this: "foo( myDynArray )", then there are now two locations that hold
28 * the addr of the same chunk of locations. So when a call is made that
29 * adds to the DynArray, and inside the DynArray expands, it only updates
30 * the original location with the new addr. Hence, the function will begin
31 * overwriting memory past the end of the old chunk, because it still has
32 * the pointer to the old chunk of locations.
33 *
34 *A dynamic array is accessed same as any other array. However, must use
35 * dyn array calls, defined in here, in order to add or increase the size.
36 * Must re-read the original array variable after any size-changing calls.
37 *To pass a DynArray as a parameter to a function, can only pass the
38 * DynArrayInfo, then inside the function, to read the addr of the first
39 * location in the chunk of locations that is the array, do this:
40 * "localArrayCopy = *(myDynArrayInfo->addrOfPtrToArray). After that, can
41 * treat localArrayCopy as a normal array, as long as don't make any calls
42 * that add or otherwise could increase the size of the array. If do make
43 * such a call, then re-copy the array via the above. Can then use the
44 * copy up until another add to the array.
45 *
46 */
20 typedef struct 47 typedef struct
21 { 48 {
22 void ***addrOfPtrToArray; //addr of array of ptrs == triple * 49 void ***addrOfPtrToArray; //addr of var that is array of ptrs == triple *
23 int32 numInArray; 50 int32 numInArray; //num entries added
24 int32 sizeOfArray; 51 int32 sizeOfArray; //num elems alloc'd
52 int32 sizeOfElem; //num bytes in one elem of array -- used in 2nd version
25 } 53 }
26 PrivDynArrayInfo; 54 PrivDynArrayInfo;
27 55
28 PrivDynArrayInfo * 56 PrivDynArrayInfo *
29 makePrivDynArrayInfoFrom( void ***addrOfPtrToArray, int32 sizeOfArray ); 57 makePrivDynArrayInfoFrom( void ***addrOfPtrToArray, int32 sizeOfArray );