diff options
author | treectrl <treectrl> | 2005-09-19 20:38:43 (GMT) |
---|---|---|
committer | treectrl <treectrl> | 2005-09-19 20:38:43 (GMT) |
commit | 1ee6a0d1bd8096531c7dc912d226c27083b8d135 (patch) | |
tree | 53b95b0a2421a410e8f177761fd2ac29944d71e4 /generic | |
parent | 304bfaefae46a6b9a9d8a56b128e679f235c8216 (diff) | |
download | tktreectrl-1ee6a0d1bd8096531c7dc912d226c27083b8d135.zip tktreectrl-1ee6a0d1bd8096531c7dc912d226c27083b8d135.tar.gz tktreectrl-1ee6a0d1bd8096531c7dc912d226c27083b8d135.tar.bz2 |
Add Tcl block comments above each function. Comment function arguments.
Diffstat (limited to 'generic')
-rw-r--r-- | generic/tkTreeUtils.c | 805 |
1 files changed, 725 insertions, 80 deletions
diff --git a/generic/tkTreeUtils.c b/generic/tkTreeUtils.c index 14ef441..381ca7e 100644 --- a/generic/tkTreeUtils.c +++ b/generic/tkTreeUtils.c @@ -5,7 +5,7 @@ * * Copyright (c) 2002-2005 Tim Baker * - * RCS: @(#) $Id: tkTreeUtils.c,v 1.36 2005/09/16 23:25:17 treectrl Exp $ + * RCS: @(#) $Id: tkTreeUtils.c,v 1.37 2005/09/19 20:38:43 treectrl Exp $ */ #include "tkTreeCtrl.h" @@ -52,7 +52,27 @@ Tk_ObjCustomOption PadAmountOption = { PadAmountOptionFree }; -void FormatResult(Tcl_Interp *interp, char *fmt, ...) +/* + *---------------------------------------------------------------------- + * + * FormatResult -- + * + * Set the interpreter's result to a formatted string. + * + * Results: + * None. + * + * Side effects: + * Interpreter's result is modified. + * + *---------------------------------------------------------------------- + */ + +void +FormatResult( + Tcl_Interp *interp, /* Current interpreter. */ + char *fmt, ... /* Format string and varargs. */ + ) { va_list ap; char buf[256]; @@ -63,7 +83,41 @@ void FormatResult(Tcl_Interp *interp, char *fmt, ...) Tcl_SetResult(interp, buf, TCL_VOLATILE); } -int Ellipsis(Tk_Font tkfont, char *string, int numBytes, int *maxPixels, char *ellipsis, int force) +/* + *---------------------------------------------------------------------- + * + * Ellipsis -- + * + * Determine the number of bytes from the string that will fit + * in the given horizontal span. If the entire string does not + * fit then determine the largest number of bytes of a substring + * with an ellipsis "..." appended that will fit. + * + * Results: + * When the return value is positive the caller should add the + * ellipsis to the string (unless the entire string fits). + * When the return value is negative the caller should not add + * the ellipsis because only a few characters fit. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + +int +Ellipsis( + Tk_Font tkfont, /* The font used to display the string. */ + char *string, /* UTF-8 string, need not be NULL-terminated. */ + int numBytes, /* Number of bytes to consider. */ + int *maxPixels, /* In: maximum line length allowed. + * Out: length of string that fits (with + * ellipsis added if needed). */ + char *ellipsis, /* NULL-terminated "..." */ + int force /* TRUE if ellipsis should always be added + * even if the whole string fits in + * maxPixels. */ + ) { char staticStr[256], *tmpStr = staticStr; int pixels, pixelsTest, bytesThatFit, bytesTest; @@ -117,8 +171,29 @@ int Ellipsis(Tk_Font tkfont, char *string, int numBytes, int *maxPixels, char *e return -bytesThatFit; } -/* Draws a horizontal 1-pixel tall dotted line */ -void HDotLine(TreeCtrl *tree, Drawable drawable, GC gc, int x1, int y1, int x2) +/* + *---------------------------------------------------------------------- + * + * HDotLine -- + * + * Draws a horizontal 1-pixel-tall dotted line. + * + * Results: + * None. + * + * Side effects: + * Stuff is drawn. + * + *---------------------------------------------------------------------- + */ + +void +HDotLine( + TreeCtrl *tree, /* Widget info. */ + Drawable drawable, /* Where to draw. */ + GC gc, /* Graphics context. */ + int x1, int y1, int x2 /* Left, top and right coordinates. */ + ) { #ifdef WIN32 TkWinDCState state; @@ -158,8 +233,28 @@ void HDotLine(TreeCtrl *tree, Drawable drawable, GC gc, int x1, int y1, int x2) #endif } -/* Draws a vertical 1-pixel wide dotted line */ -void VDotLine(TreeCtrl *tree, Drawable drawable, GC gc, int x1, int y1, int y2) +/* + *---------------------------------------------------------------------- + * + * VDotLine -- + * + * Draws a vertical 1-pixel-wide dotted line. + * + * Results: + * None. + * + * Side effects: + * Stuff is drawn. + * + *---------------------------------------------------------------------- + */ + +void +VDotLine( + TreeCtrl *tree, /* Widget info. */ + Drawable drawable, /* Where to draw. */ + GC gc, /* Graphics context. */ + int x1, int y1, int y2) /* Left, top, and bottom coordinates. */ { #ifdef WIN32 TkWinDCState state; @@ -199,8 +294,36 @@ void VDotLine(TreeCtrl *tree, Drawable drawable, GC gc, int x1, int y1, int y2) #endif } -/* Draws 0 or more sides of a rectangle, dot-on dot-off, XOR style */ -void DrawActiveOutline(TreeCtrl *tree, Drawable drawable, int x, int y, int width, int height, int open) +/* + *---------------------------------------------------------------------- + * + * DrawActiveOutline -- + * + * Draws 0 or more sides of a rectangle, dot-on dot-off, XOR style. + * This is used by rectangle Elements to indicate the "active" + * item. + * + * Results: + * None. + * + * Side effects: + * Stuff is drawn. + * + *---------------------------------------------------------------------- + */ + +void +DrawActiveOutline( + TreeCtrl *tree, /* Widget info. */ + Drawable drawable, /* Where to draw. */ + int x, int y, /* Left and top coordinates. */ + int width, int height, /* Size of rectangle. */ + int open /* Bitmask of edges not to draw: + * 0x01: left + * 0x02: top + * 0x04: right + * 0x08: bottom */ + ) { #ifdef WIN32 int wx = x + tree->drawableXOrigin; @@ -317,11 +440,10 @@ void DrawActiveOutline(TreeCtrl *tree, Drawable drawable, int x, int y, int widt #endif } -void DotRect(TreeCtrl *tree, Drawable drawable, int x, int y, int width, int height) -{ - DrawActiveOutline(tree, drawable, x, y, width, height, 0); -} - +/* + * The following structure is used when drawing a number of dotted XOR + * rectangles. + */ struct DotStatePriv { TreeCtrl *tree; @@ -339,7 +461,31 @@ struct DotStatePriv #endif }; -void DotRect_Setup(TreeCtrl *tree, Drawable drawable, DotState *p) +/* + *---------------------------------------------------------------------- + * + * DotRect_Setup -- + * + * Prepare a drawable for drawing a series of dotted XOR rectangles. + * + * Results: + * State info is returned to be used by the other DotRect_xxx() + * procedures. + * + * Side effects: + * On Win32 and OSX the device context/graphics port is altered + * in preparation for drawing. On X11 a new graphics context is + * created. + * + *---------------------------------------------------------------------- + */ + +void +DotRect_Setup( + TreeCtrl *tree, /* Widget info. */ + Drawable drawable, /* Where to draw. */ + DotState *p /* Where to save state info. */ + ) { struct DotStatePriv *dotState = (struct DotStatePriv *) p; #ifdef WIN32 @@ -403,7 +549,28 @@ void DotRect_Setup(TreeCtrl *tree, Drawable drawable, DotState *p) #endif } -void DotRect_Draw(DotState *p, int x, int y, int width, int height) +/* + *---------------------------------------------------------------------- + * + * DotRect_Draw -- + * + * Draw a dotted XOR rectangle. + * + * Results: + * None. + * + * Side effects: + * Stuff is drawn. + * + *---------------------------------------------------------------------- + */ + +void +DotRect_Draw( + DotState *p, /* Info returned by DotRect_Setup(). */ + int x, int y, /* Left and top coordinates. */ + int width, int height /* Size of rectangle. */ + ) { struct DotStatePriv *dotState = (struct DotStatePriv *) p; #ifdef WIN32 @@ -491,7 +658,27 @@ void DotRect_Draw(DotState *p, int x, int y, int width, int height) #endif } -void DotRect_Restore(DotState *p) +/* + *---------------------------------------------------------------------- + * + * DotRect_Restore -- + * + * Restore the drawing environment. + * + * Results: + * None. + * + * Side effects: + * On Win32 and OSX the device context/graphics port is restored. + * On X11 a new graphics context is freed. + * + *---------------------------------------------------------------------- + */ + +void +DotRect_Restore( + DotState *p /* Info returned by DotRect_Setup(). */ + ) { struct DotStatePriv *dotState = (struct DotStatePriv *) p; #ifdef WIN32 @@ -509,8 +696,31 @@ void DotRect_Restore(DotState *p) } #ifdef MAC_OSX_TK -void DrawXORLine(Display *display, Drawable drawable, int x1, int y1, - int x2, int y2) + +/* + *---------------------------------------------------------------------- + * + * DrawXORLine -- + * + * Draw a 1-pixel thick XOR line (not dotted). This is used + * to draw the vertical column proxy when resizing columns. + * + * Results: + * None. + * + * Side effects: + * Stuff is drawn. + * + *---------------------------------------------------------------------- + */ + +void +DrawXORLine( + Display *display, /* Display. */ + Drawable drawable, /* Where to draw. */ + int x1, int y1, /* Left, top. */ + int x2, int y2 /* Bottom, right. */ + ) { MacDrawable *macWin = (MacDrawable *) drawable; CGrafPtr saveWorld; @@ -534,9 +744,32 @@ void DrawXORLine(Display *display, Drawable drawable, int x1, int y1, HidePen(); SetGWorld(saveWorld, saveDevice); } -#endif -void Tk_FillRegion(Display *display, Drawable drawable, GC gc, TkRegion rgn) +#endif /* MAC_OSX_TK */ + +/* + *---------------------------------------------------------------------- + * + * Tk_FillRegion -- + * + * Paint a region with the foreground color of a graphics context. + * + * Results: + * None. + * + * Side effects: + * Stuff is drawn. + * + *---------------------------------------------------------------------- + */ + +void +Tk_FillRegion( + Display *display, /* Display. */ + Drawable drawable, /* Where to draw. */ + GC gc, /* Foreground color. */ + TkRegion rgn /* Region to paint. */ + ) { #ifdef WIN32 HDC dc; @@ -582,7 +815,27 @@ void Tk_FillRegion(Display *display, Drawable drawable, GC gc, TkRegion rgn) #endif } -void Tk_OffsetRegion(TkRegion region, int xOffset, int yOffset) +/* + *---------------------------------------------------------------------- + * + * Tk_OffsetRegion -- + * + * Offset a region. + * + * Results: + * None. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + +void +Tk_OffsetRegion( + TkRegion region, /* Region to modify. */ + int xOffset, int yOffset /* Horizontal and vertical offsets. */ + ) { #ifdef WIN32 OffsetRgn((HRGN) region, xOffset, yOffset); @@ -593,8 +846,32 @@ void Tk_OffsetRegion(TkRegion region, int xOffset, int yOffset) #endif } -int Tree_ScrollWindow(TreeCtrl *tree, GC gc, int x, int y, - int width, int height, int dx, int dy, TkRegion damageRgn) +/* + *---------------------------------------------------------------------- + * + * Tree_ScrollWindow -- + * + * Wrapper around TkScrollWindow() to fix an apparent bug with the + * Mac/OSX versions. + * + * Results: + * None. + * + * Side effects: + * Stuff is scrolled in a drawable. + * + *---------------------------------------------------------------------- + */ + +int +Tree_ScrollWindow( + TreeCtrl *tree, /* Widget info. */ + GC gc, /* Arg to TkScrollWindow(). */ + int x, int y, /* Arg to TkScrollWindow(). */ + int width, int height, /* Arg to TkScrollWindow(). */ + int dx, int dy, /* Arg to TkScrollWindow(). */ + TkRegion damageRgn /* Arg to TkScrollWindow(). */ + ) { int result = TkScrollWindow(tree->tkwin, gc, x, y, width, height, dx, dy, damageRgn); @@ -608,7 +885,29 @@ int Tree_ScrollWindow(TreeCtrl *tree, GC gc, int x, int y, return result; } -void UnsetClipMask(TreeCtrl *tree, Drawable drawable, GC gc) +/* + *---------------------------------------------------------------------- + * + * UnsetClipMask -- + * + * Wrapper around XSetClipMask(). On Win32 Tk_DrawChars() does + * not clear the clipping region. + * + * Results: + * None. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + +void +UnsetClipMask( + TreeCtrl *tree, /* Widget info. */ + Drawable drawable, /* Where to draw. */ + GC gc /* Graphics context to modify. */ + ) { XSetClipMask(tree->display, gc, None); #ifdef WIN32 @@ -624,8 +923,34 @@ void UnsetClipMask(TreeCtrl *tree, Drawable drawable, GC gc) #endif } -void Tree_DrawBitmapWithGC(TreeCtrl *tree, Pixmap bitmap, Drawable drawable, - GC gc, int src_x, int src_y, int width, int height, int dest_x, int dest_y) +/* + *---------------------------------------------------------------------- + * + * Tree_DrawBitmapWithGC -- + * + * Draw part of a bitmap. + * + * Results: + * None. + * + * Side effects: + * Stuff is drawn. + * + *---------------------------------------------------------------------- + */ + +void +Tree_DrawBitmapWithGC( + TreeCtrl *tree, /* Widget info. */ + Pixmap bitmap, /* Bitmap to draw. */ + Drawable drawable, /* Where to draw. */ + GC gc, /* Graphics context. */ + int src_x, int src_y, /* Left and top of part of bitmap to copy. */ + int width, int height, /* Width and height of part of bitmap to + * copy. */ + int dest_x, int dest_y /* Left and top coordinates to copy part of + * the bitmap to. */ + ) { #ifdef WIN32 TkpClipMask *clipPtr = (TkpClipMask *) gc->clip_mask; @@ -658,9 +983,35 @@ void Tree_DrawBitmapWithGC(TreeCtrl *tree, Pixmap bitmap, Drawable drawable, XSetClipOrigin(tree->display, gc, 0, 0); } -void Tree_DrawBitmap(TreeCtrl *tree, Pixmap bitmap, Drawable drawable, - XColor *fg, XColor *bg, - int src_x, int src_y, int width, int height, int dest_x, int dest_y) +/* + *---------------------------------------------------------------------- + * + * Tree_DrawBitmap -- + * + * Draw part of a bitmap. + * + * Results: + * None. + * + * Side effects: + * Stuff is drawn. + * + *---------------------------------------------------------------------- + */ + +void +Tree_DrawBitmap( + TreeCtrl *tree, /* Widget info. */ + Pixmap bitmap, /* Bitmap to draw. */ + Drawable drawable, /* Where to draw. */ + XColor *fg, XColor *bg, /* Foreground and background colors. + * May be NULL. */ + int src_x, int src_y, /* Left and top of part of bitmap to copy. */ + int width, int height, /* Width and height of part of bitmap to + * copy. */ + int dest_x, int dest_y /* Left and top coordinates to copy part of + * the bitmap to. */ + ) { XGCValues gcValues; GC gc; @@ -701,8 +1052,32 @@ void Tree_DrawBitmap(TreeCtrl *tree, Pixmap bitmap, Drawable drawable, #define TK_PHOTOPUTZOOMEDBLOCK Tk_PhotoPutZoomedBlock #endif +/* + *---------------------------------------------------------------------- + * + * XImage2Photo -- + * + * Copy pixels from an XImage to a Tk photo image. + * + * Results: + * None. + * + * Side effects: + * The given photo image is blanked and all the pixels from the + * XImage are put into the photo image. + * + *---------------------------------------------------------------------- + */ + #if defined(WIN32) || defined(MAC_TCL) || defined(MAC_OSX_TK) -void XImage2Photo(Tcl_Interp *interp, Tk_PhotoHandle photoH, XImage *ximage, int alpha) + +void +XImage2Photo( + Tcl_Interp *interp, /* Current interpreter. */ + Tk_PhotoHandle photoH, /* Existing photo image. */ + XImage *ximage, /* XImage to copy pixels from. */ + int alpha /* Desired transparency of photo image.*/ + ) { Tk_PhotoImageBlock photoBlock; unsigned char *pixelPtr; @@ -765,8 +1140,16 @@ void XImage2Photo(Tcl_Interp *interp, Tk_PhotoHandle photoH, XImage *ximage, int Tcl_Free((char *) pixelPtr); } -#else /* X11 */ -void XImage2Photo(Tcl_Interp *interp, Tk_PhotoHandle photoH, XImage *ximage, int alpha) + +#else /* not X11 */ + +void +XImage2Photo( + Tcl_Interp *interp, /* Current interpreter. */ + Tk_PhotoHandle photoH, /* Existing photo image. */ + XImage *ximage, /* XImage to copy pixels from. */ + int alpha /* Desired transparency of photo image.*/ + ) { Tk_Window tkwin = Tk_MainWindow(interp); Display *display = Tk_Display(tkwin); @@ -852,7 +1235,8 @@ void XImage2Photo(Tcl_Interp *interp, Tk_PhotoHandle photoH, XImage *ximage, int Tcl_Free((char *) pixelPtr); ckfree((char *) xcolors); } -#endif + +#endif /* X11 */ /* * Replacement for Tk_TextLayout stuff. Allows the caller to break lines @@ -1655,9 +2039,28 @@ PadAmountOptionFree(clientData, tkwin, internalPtr) } } -/*****/ +/* + *---------------------------------------------------------------------- + * + * ObjectIsEmpty -- + * + * This procedure tests whether the string value of an object is + * empty. + * + * Results: + * The return value is 1 if the string value of objPtr has length + * zero, and 0 otherwise. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ -int ObjectIsEmpty(Tcl_Obj *obj) +int +ObjectIsEmpty( + Tcl_Obj *obj /* Object to test. May be NULL. */ + ) { int length; @@ -1669,10 +2072,29 @@ int ObjectIsEmpty(Tcl_Obj *obj) return (length == 0); } -void PerStateInfo_Free( - TreeCtrl *tree, - PerStateType *typePtr, - PerStateInfo *pInfo) +/* + *---------------------------------------------------------------------- + * + * PerStateInfo_Free -- + * + * Frees memory and resources associated with a single per-state + * option. pInfo is set to an empty state ready to be used again. + * + * Results: + * None. + * + * Side effects: + * Memory is deallocated. Colors, etc are freed. + * + *---------------------------------------------------------------------- + */ + +void +PerStateInfo_Free( + TreeCtrl *tree, /* Widget info. */ + PerStateType *typePtr, /* Type-specific functions and values. */ + PerStateInfo *pInfo /* Per-state info to free. */ + ) { PerStateData *pData = pInfo->data; int i; @@ -1698,11 +2120,33 @@ void PerStateInfo_Free( pInfo->count = 0; } -int PerStateInfo_FromObj( - TreeCtrl *tree, - StateFromObjProc proc, - PerStateType *typePtr, - PerStateInfo *pInfo) +/* + *---------------------------------------------------------------------- + * + * PerStateInfo_FromObj -- + * + * Parse a Tcl_Obj to an array of PerStateData. The current data + * is freed (if any). If the Tcl_Obj is NULL then pInfo is left in + * an empty state ready to be used again. + * + * Results: + * A standard Tcl result. + * + * Side effects: + * Memory is allocated/deallocated. + * + *---------------------------------------------------------------------- + */ + +int +PerStateInfo_FromObj( + TreeCtrl *tree, /* Widget info. */ + StateFromObjProc proc, /* Procedure used to turn a Tcl_Obj into + * a state bit-flag. */ + PerStateType *typePtr, /* Type-specific functions and values. */ + PerStateInfo *pInfo /* Per-state info to return. pInfo->obj + * must be NULL or point to a valid Tcl_Obj. */ + ) { int i, j; int objc, objc2; @@ -1793,12 +2237,32 @@ freeIt: return TCL_ERROR; } -PerStateData *PerStateInfo_ForState( - TreeCtrl *tree, - PerStateType *typePtr, - PerStateInfo *pInfo, - int state, - int *match) +/* + *---------------------------------------------------------------------- + * + * PerStateInfo_ForState -- + * + * Return the best-matching PerStateData for a given state. + * + * Results: + * The return value is a pointer to the best-matching PerStateData. + * *match is set to a MATCH_xxx constant. NULL is returned if + * no appropriate PerStateData was found. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + +PerStateData * +PerStateInfo_ForState( + TreeCtrl *tree, /* Widget info. */ + PerStateType *typePtr, /* Type-specific functions and values. */ + PerStateInfo *pInfo, /* Per-state info to search. */ + int state, /* State bit-flags to compare. */ + int *match /* Returned MATCH_xxx constant. */ + ) { PerStateData *pData = pInfo->data; int stateOff = ~state, stateOn = state; @@ -1839,12 +2303,35 @@ PerStateData *PerStateInfo_ForState( return NULL; } -Tcl_Obj *PerStateInfo_ObjForState( - TreeCtrl *tree, - PerStateType *typePtr, - PerStateInfo *pInfo, - int state, - int *match) +/* + *---------------------------------------------------------------------- + * + * PerStateInfo_ObjForState -- + * + * Return a Tcl_Obj from the list object that was parsed by + * PerStateInfo_FromObj(). pInfo is searched for the best-matching + * PerStateData for the given state and the object used to + * create that PerStateData is returned. + * + * Results: + * *match is set to a MATCH_xxx constant. NULL is returned if + * no appropriate PerStateData was found. The object should not + * be modified by the caller. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + +Tcl_Obj * +PerStateInfo_ObjForState( + TreeCtrl *tree, /* Widget info. */ + PerStateType *typePtr, /* Type-specific functions and values. */ + PerStateInfo *pInfo, /* Per-state info to search. */ + int state, /* State bit-flags to compare. */ + int *match /* Returned MATCH_xxx constant. */ + ) { PerStateData *pData; Tcl_Obj *obj; @@ -1866,11 +2353,32 @@ Tcl_Obj *PerStateInfo_ObjForState( return NULL; } +/* + *---------------------------------------------------------------------- + * + * PerStateInfo_Undefine -- + * + * Called when a user-defined state flag is undefined. The state + * flag is cleared from every PerStateData using that flag. The + * list object that was parsed by PerStateInfo_FromObj() is modified + * by removing any reference to the undefined state. + * + * Results: + * The return value is a boolean indicating whether or not pInfo + * was modified. + * + * Side effects: + * The list object pointed to by pInfo->obj may be recreated. + * + *---------------------------------------------------------------------- + */ + int PerStateInfo_Undefine( - TreeCtrl *tree, - PerStateType *typePtr, - PerStateInfo *pInfo, - int state) + TreeCtrl *tree, /* Widget info. */ + PerStateType *typePtr, /* Type-specific functions and values. */ + PerStateInfo *pInfo, /* Per-state info to modify. */ + int state /* State bit-flag that was undefined. */ + ) { PerStateData *pData = pInfo->data; int i, j, numStates, stateOff, stateOn; @@ -1910,8 +2418,8 @@ int PerStateInfo_Undefine( j++; } /* Given {bitmap {state1 state2 state3}}, we just invalidated - * the string rep of the sublist {state1 ...}, but not - * the parent list */ + * the string rep of the sublist {state1 state2 state3}, but not + * the parent list. */ Tcl_InvalidateStringRep(configObj); modified = 1; } @@ -2423,7 +2931,8 @@ typedef struct AllocList AllocList; typedef struct AllocData AllocData; /* - * One of the following structures exists for each client block of memory. + * One of the following structures exists for each client piece of memory. + * These structures are allocated in arrays (blocks). */ struct AllocElem @@ -2431,25 +2940,25 @@ struct AllocElem AllocElem *next; int free; char body[1]; /* First byte of client's space. Actual - * size of this field will be larger than - * one. */ + * size of this field will be larger than + * one. */ }; /* - * One of the following structures maintains a list of blocks of AllocElems + * One of the following structures maintains an array of blocks of AllocElems * of the same size. */ struct AllocList { - int size; /* Size of every AllocElem.body[] */ - AllocElem *head; - AllocList *next; /* Points to an AllocList with a different .size */ + int size; /* Size of every AllocElem.body[] */ + AllocElem *head; /* Top of stack of unused pieces of memory. */ AllocElem **blocks; /* Array of pointers to allocated blocks. The blocks * may contain a different number of elements. */ - int blockCount; /* Number of array elements in .blocks */ - int blockSize; /* The number of AllocElems per block to allocate. - * Starts at 16 and gets double up to 1024. */ + int blockCount; /* Number of array elements in .blocks */ + int blockSize; /* The number of AllocElems per block to allocate. + * Starts at 16 and gets doubled up to 1024. */ + AllocList *next; /* Points to an AllocList with a different .size */ }; /* @@ -2458,7 +2967,7 @@ struct AllocList struct AllocData { - AllocList *freeLists; + AllocList *freeLists; /* Linked list. */ }; /* @@ -2470,7 +2979,29 @@ struct AllocData #define BODY_OFFSET \ ((unsigned long) (&((AllocElem *) 0)->body)) -char *AllocHax_Alloc(ClientData data, int size) +/* + *---------------------------------------------------------------------- + * + * AllocHax_Alloc -- + * + * Return storage for a piece of data of the given size. + * + * Results: + * The return value is a pointer to memory for the caller's + * use. + * + * Side effects: + * Memory may be allocated. + * + *---------------------------------------------------------------------- + */ + +char * +AllocHax_Alloc( + ClientData data, /* Pointer to AllocData created by + * AllocHax_Init(). */ + int size /* Number of bytes needed. */ + ) { AllocList *freeLists = ((AllocData *) data)->freeLists; AllocList *freeList = freeLists; @@ -2528,7 +3059,32 @@ char *AllocHax_Alloc(ClientData data, int size) return result->body; } -void AllocHax_Free(ClientData data, char *ptr, int size) +/* + *---------------------------------------------------------------------- + * + * AllocHax_Free -- + * + * Mark a piece of memory as free for reuse. + * + * Results: + * The piece of memory is added to a list of free pieces of the + * same size. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + +void +AllocHax_Free( + ClientData data, /* Pointer to AllocData created by + * AllocHax_Init(). */ + char *ptr, /* Memory to mark for reuse. Must have + * been allocated by AllocHax_Alloc(). */ + int size /* Number of bytes. Must match the size + * passed to AllocHax_CAlloc(). */ + ) { AllocList *freeLists = ((AllocData *) data)->freeLists; AllocList *freeList = freeLists; @@ -2555,26 +3111,115 @@ void AllocHax_Free(ClientData data, char *ptr, int size) freeList->head = elem; } -char *AllocHax_CAlloc(ClientData data, int size, int count, int roundUp) +/* + *---------------------------------------------------------------------- + * + * AllocHax_CAlloc -- + * + * Return storage for an array of pieces of memory. + * + * Results: + * Pointer to the available memory. + * + * Side effects: + * Memory may be allocated. + * + *---------------------------------------------------------------------- + */ + +char * +AllocHax_CAlloc( + ClientData data, /* Pointer to AllocData created by + * AllocHax_Init(). */ + int size, /* Number of bytes needed for each piece + * of memory. */ + int count, /* Number of pieces of memory needed. */ + int roundUp /* Positive number used to reduce the number + * of lists of memory pieces of different + * size. */ + ) { int n = (count / roundUp) * roundUp + ((count % roundUp) ? roundUp : 0); return AllocHax_Alloc(data, size * n); } -void AllocHax_CFree(ClientData data, char *ptr, int size, int count, int roundUp) +/* + *---------------------------------------------------------------------- + * + * AllocHax_CFree -- + * + * Mark a piece of memory as free for reuse. + * + * Results: + * The piece of memory is added to a list of free pieces of the + * same size. + * + * Side effects: + * None. + * + *---------------------------------------------------------------------- + */ + +void +AllocHax_CFree( + ClientData data, /* Pointer to AllocData created by + * AllocHax_Init(). */ + char *ptr, /* Memory to mark for reuse. Must have + * been allocated by AllocHax_CAlloc(). */ + int size, /* Same arg to AllocHax_CAlloc(). */ + int count, /* Same arg to AllocHax_CAlloc(). */ + int roundUp /* Same arg to AllocHax_CAlloc(). */ + ) { int n = (count / roundUp) * roundUp + ((count % roundUp) ? roundUp : 0); AllocHax_Free(data, ptr, size * n); } -ClientData AllocHax_Init(void) +/* + *---------------------------------------------------------------------- + * + * AllocHax_Init -- + * + * Allocate and initialize a new memory-manager record. + * + * Results: + * Pointer to memory-manager record. + * + * Side effects: + * Memory is allocated. + * + *---------------------------------------------------------------------- + */ + +ClientData +AllocHax_Init(void) { AllocData *data = (AllocData *) ckalloc(sizeof(AllocData)); data->freeLists = NULL; return data; } -void AllocHax_Finalize(ClientData data) +/* + *---------------------------------------------------------------------- + * + * AllocHax_Finalize -- + * + * Free all the memory associated with a memory-manager record. + * + * Results: + * Pointer to memory-manager record. + * + * Side effects: + * Memory is deallocated. + * + *---------------------------------------------------------------------- + */ + +void +AllocHax_Finalize( + ClientData data /* Pointer to AllocData created by + * AllocHax_Init(). */ + ) { AllocList *freeList = ((AllocData *) data)->freeLists; int i; |