ChunkArrayElementToPtr()

void *  ChunkArrayElementToPtr(
        optr           array,                                  /* optr to chunk array */
        word           elementNumber,                                  /* Element to get address of */
        void *         elementSize);                                   /* Write element's size here */

This routine translates the index of an element into the element's address. The routine is passed an optr to the chunk array, the index of the element in question, and a pointer to a word-sized variable. It returns a pointer to the element. If the elements in the array are of variable size, it writes the size of the element to the variable pointed to by the elementSize pointer. If the elements are of uniform size, it does not do this.

If the array index is out of bounds, the routine returns a pointer to the last element in the array. The routine will also do this if you pass the constant CA_LAST_ELEMENT.

Include: chunkarr.h

Tips and Tricks: If you are not interested in the element's size, pass a null pointer as the third argument.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

Warnings: The error-checking version fatal-errors if passed the index CA_NULL_ELEMENT (i.e. 0xffff, or -1).

ChunkArrayElementToPtrHandles()

void *  ChunkArrayElementToPtrHandles(
        Memhandle              mh,                                     /* Handle of LMem heap's block */
        ChunkHandle            chunk,                                  /* Handle of chunk array */
        word           elementNumber,                                  /* Element to get address of */
        void *         elementSize);                                   /* Write element's size here */

This routine is just like ChunkArrayElementToPtr() , except that the chunk array is specified with its global and chunk handles, instead of with an optr.

Include: chunkarr.h

Tips and Tricks: If you are not interested in the element's size, pass a null pointer as the fourth argument.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

See Also: ChunkArrayPtrToElement().

Warnings: The error-checking version fatal-errors if passed the index CA_NULL_ELEMENT (i.e. 0xffff, or -1).

ChunkArrayEnum()

Boolean ChunkArrayEnum(
        optr           array,                  /* optr to chunk array */
        void *         enumData,                       /* This is passed to callback routine */
        Boolean _pascal (*callback) (void *element, void *enumData));
        /* callback called for each element; returns TRUE to stop */

This routine lets you apply a procedure to every element in a chunk array. The routine is passed an optr to the chunk array, a pointer (which is passed to the callback routine), and a pointer to a Boolean callback routine. The callback routine, in turn, is called once for each element in the array, and is passed two arguments: a pointer to an element and the pointer which was passed to ChunkArrayEnum() . If the callback routine ever returns true for an element, ChunkArrayEnum() will stop with that element and return true . If it enumerates every element without being aborted, it returns false.

The callback routine can call such routines as ChunkArrayAppend(), ChunkArrayInsertAt(), and ChunkArrayDelete() . ChunkArrayEnum() will see to it that every element is enumerated exactly once. The callback routine can even make a nested call to ChunkArrayEnum() ; the nested call will be completed for every element before the outer call goes to the next element. The callback routine should be declared _pascal.

You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

ChunkArrayEnumHandles()

Boolean ChunkArrayEnumHandles(
        MemHandle              mh,                     /* Handle of LMem heap's block */
        ChunkHandle            ch,                     /* Handle of chunk array */
        void *         enumData,                       /* Buffer used by callback routine */
        Boolean _pascal (*callback) (void *element, void *enumData));
        /* callback called for each element; returns TRUE to stop */

This routine is exactly like ChunkArrayEnum() , except that the chunk array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ChunkArrayEnumRange()

Boolean         ChunkArrayEnumRange(
        optr   array,  /* optr to chunk array */
        word   startElement,   /* Start enumeration with this element */
        word   count,  /* Process this many elements */
        void * enumData,       /* This is passed to the callback routine */
        Boolean _pascal (*callback)            /* Return TRUE to halt enumeration */
               (void *element, void *enumData));

This routine is exactly like ChunkArrayEnum() (described above), except that it acts on a limited portion of the array. It is passed two additional arguments: the index of the starting element, and the number of elements to process. It will begin the enumeration with the element specified (remember, the first element in a chunk array has an index of zero). If the count passed would take the enumeration past the end of the array, ChunkArrayEnumRange() will automatically stop with the last element. You can instruct ChunkArrayEnumRange() to process all elements by passing a count of CA_LAST_ELEMENT.

Include: chunkarr.h

Warnings: The start element must be within the bounds of the array.

See Also: ChunkArrayEnum().

ChunkArrayEnumRangeHandles()

Boolean         ChunkArrayEnumRangeHandles(
        MemHandle      mh,     /* Handle of LMem heap's block */
        ChunkHandle    ch,     /* Handle of chunk array */
        word   startElement,   /* Start enumeration with this element */
        word   count,  /* Process this many elements */
        void * enumData,       /* This is passed to the callback routine */
        Boolean _pascal (*callback)            /* Return TRUE to halt enumeration */
               (void *element, void *enumData));

This routine is exactly like ChunkArrayEnumRange() , except that the chunk array is specified by its global and chunk handles (instead of with an optr).

ChunkArrayGetCount()

word    ChunkArrayGetCount(
        optr   array);                         /* optr of chunk array */

This routine returns the number of elements in the specified chunk array.

Include: chunkarr.h

Tips and Tricks: It is usually faster to examine the CAH _count field of the ChunkArrayHeader . This field is the first word of the ChunkArrayHeader (and therefore of the chunk). It contains the number of elements in the chunk array.

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

See Also: ChunkArrayHeader.