Reordered and tidied.

[mLib] / track.h

/* -*-c-*-
 *
 * $Id: track.h,v 1.1 1998/06/17 23:44:42 mdw Exp $
 *
 * Tracing functions for debugging
 *
 * (c) 1998 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * mLib is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with mLib; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------*
 *
 * $Log: track.h,v $
 * Revision 1.1  1998/06/17 23:44:42  mdw
 * Initial revision
 *
 */

#ifndef TRACK_H
#define TRACK_H

#ifdef __cplusplus
  extern "C" {
#endif

#include <stdlib.h>

/*----- Options and conventions -------------------------------------------*
 *
 * The following macros affect the tracking system:
 *
 * @TRACK_ENABLE@:      Enable tracking of memory allocations
 * @TRACK_BLAME@:       Register my context blocks in allocations
 *
 * The reason there are two switches is simple.  It's often the case that a
 * library routine allocates memory for its client.  Therefore, whether we
 * want to record the library or the client depends on how much we trust
 * the two pieces of software.  Setting @TRACK_ENABLE@ and @TRACK_BLAME@
 * suggests that the current source file might leak memory, so we want its
 * context markers in the list.  Setting @TRACK_ENABLE@ but not
 * @TRACK_BLAME@ suggests that we trust this code, but not the code which
 * calls it, so we want to preserve the caller's context markers.
 *
 * Got it?  Good.
 */

/*----- Type definitions --------------------------------------------------*/

/* --- A context buffer --- */

typedef struct track_ctx {
  struct track_ctx *next;
  const char *s;
} track_ctx;

/*----- Functions provided ------------------------------------------------*/

/* --- @track_setLevel@ --- *
 *
 * Arguments:   @unsigned int l@ = tracing level for allocation messages
 *
 * Returns:     ---
 *
 * Use:         Sets the trace level for allocation messages.
 */

extern void track_setLevel(unsigned int /*l*/);

/* --- @track_pushContext@ --- *
 *
 * Arguments:   @track_ctx *ctx@ = context holder to push
 *
 * Returns:     ---
 *
 * Use:         Pushes the given context block onto the stack.
 */

extern void track_pushContext(track_ctx */*ctx*/);

/* --- @track_popContext@ --- *
 *
 * Arguments:   @track_ctx *ctx@ = context holder to pop
 *
 * Returns:     ---
 *
 * Use:         Removes the given context block from the stack.
 */

extern void track_popContext(track_ctx */*ctx*/);

/* --- @track_malloc@ --- *
 *
 * Arguments:   @size_t sz@ = size requested
 *
 * Returns:     Pointer to allocated space, or null
 *
 * Use:         Allocates memory, and tracks how much is allocated.
 */

extern void *track_malloc(size_t /*sz*/);

/* --- @track_free@ --- *
 *
 * Arguments:   @void *p@ = pointer to an allocated block
 *
 * Returns:     ---
 *
 * Use:         Frees memory, and tracks how much is still allocated.
 */

extern void track_free(void */*p*/);

/* --- @track_realloc@ --- *
 *
 * Arguments:   @void *p@ = pointer to an allocated block
 *              @size_t sz@ = how big it wants to be
 *
 * Returns:     Pointer to the new block.
 *
 * Use:         Reallocates a block, tracking how much memory is still
 *              available.
 */

extern void *track_realloc(void */*p*/, size_t /*sz*/);

/* --- @track_used@ --- *
 *
 * Arguments:   ---
 *
 * Returns:     A count of how much memory is used currently.
 *
 * Use:         Returns the amount of memory which the @track_@-functions
 *              above have counted as being currently allocated.
 */

extern unsigned long track_used(void);

/* --- @track_list@ --- *
 *
 * Arguments:   @unsigned int l@ = trace level to use
 *
 * Returns:     ---
 *
 * Use:         Traces a dump of the currently known blocks.  Combined with
 *              a verbose dump of allocations and deallocations, and a
 *              good idea of which blocks were allocated where, this can
 *              be useful for locating memory leaks.  It's not exactly a
 *              picnic, though.
 */

extern void track_list(unsigned int l);

/*----- Macro wrappers ----------------------------------------------------*/


/* --- If tracking is to be done, set it up --- */

#ifdef TRACK_ENABLE
#  undef malloc
#  define malloc(sz) track_malloc(sz)
#  undef free
#  define free(p) track_free(p)
#  undef realloc
#  define realloc(p, sz) track_realloc(p, sz)
#endif

/* --- Provide a context for doing track-related things --- */

#ifdef TRACK_ENABLE
#  define TRACK(x) x
#else
#  define TRACK(x)
#endif

/* --- Handle contexts --- */

#if defined(TRACK_ENABLE) && defined(TRACK_BLAME)
#  define TRACK_NCTX(name, string) track__context name = { 0, string }
#  define TRACK_NPUSH(name) track_pushContext(name)
#  define TRACK_NPOP(name) track_popContext(name)
#  define TRACK_CTX(string) TRACK_NCTX(track__localContext, string)
#  define TRACK_PUSH TRACK_NPUSH(track__localContext)
#  define TRACK_POP TRACK_NPOP(track__localContext)
#else
#  define TRACK_NCTX(name, string)
#  define TRACK_NPUSH(name) ((void)0)
#  define TRACK_NPOP(name) ((void)0)
#  define TRACK_CTX(string)
#  define TRACK_PUSH ((void)0)
#  define TRACK_POP ((void)0)
#endif

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif