Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

gm_mark.c File Reference

#include "gm.h"

Data Structures

union  gm_mark_reference
struct  gm_mark_set

Typedefs

typedef gm_mark_reference gm_mark_reference_t

Functions

GM_ENTRY_POINT gm_status_t gm_mark (struct gm_mark_set *set, gm_mark_t *m)
GM_ENTRY_POINT int gm_mark_is_valid (struct gm_mark_set *set, gm_mark_t *m)
GM_ENTRY_POINT void gm_unmark (struct gm_mark_set *set, gm_mark_t *m)
GM_ENTRY_POINT gm_status_t gm_create_mark_set (struct gm_mark_set **msp, unsigned long cnt)
GM_ENTRY_POINT void gm_destroy_mark_set (struct gm_mark_set *set)
GM_ENTRY_POINT void gm_unmark_all (struct gm_mark_set *set)

Detailed Description

This file implements a constant-time system for marking memory locations and verifying that they have not been corrupted. All operations have average execution time of O(1). If enough marks were specified in the call to gm_create_mark_set(), then all operations have worst-case performance of O(1); otherwise, the worst-case performance is O(N) where N is the number of marks in the mark set.

We do not simply use a magic number as a mark, or a mark set identifier as a mark, since this technique can lead to false positives where unitialized marks appear valid. With this system, any localized corruption of a mark or the mark set database will result in the mark being determined to be invalid. False positives in this system require that both the mark and mark set database be corrupted in a consistent way, which is basically impossible.

This implementation was inspired by a challenge from John Regehr, who was forwarding a challenge from a UVA CS professor, paraphrased as follows: Can you implement the functionality of an array where initialization, insertion, removal, and test for presense of an array element each has execution time bounded by a constant, assuming you are initially provided with a pointer to a sufficient amount of uninitialized memory. You are only allowed O(N) storage, where N is the max number of entries." The anwer is "Yes" and a lot of the same tricks are used here.

The GM "mark" API is introduced in GM-1.4. It allows the creation and destruction of mark sets, which allow mark addition, mark removal, and test for mark in mark set operations to be performed in constant time. Marks may be members of only one mark set at a time. Marks have the very unusual property that they need not be initialized before use.

All operations on marks are extremely efficient. Mark initialization requires zero time. Removing a mark from a mark set and testing for mark inclusion in a mark set take constant time. Addition of a mark to a mark set takes O(constant) time, assuming the marks set was created with support for a sufficient number of marks; otherwise, it requires O(constant) average time. Finally, creation and destruction of a mark set take time comperable to the time required for a single call to `malloc()' and `free()', respectively.

Because marks need not be initialized before use, they can actually be used to determine if other objects have been initialized. This is done by putting a mark in the object, and adding the mark to a "mark set of marks in initialized objects" once the object has been initialized. This is similar to one common use of "magic numbers" for debugging purposes, except that it is immune to the possibility that the uninitialized magic number contained the magic number before initialization, so such marks can be used for non-debugging purposes. Therefore, marks can be used in ways that magic numbers cannot.

Marks have a nice set of properties that each mark in a mark set has a unique value and if this value is corrupted, then the mark is implicitly removed from the mark set. This makes marks useful for detecting memory corruption, and are less prone to false negatives than are magic numbers, which proliferate copies of a single value.

Finally, marks are location-dependent. This means that if a mark is copied, the copy will not be a member of the mark set.


Typedef Documentation

typedef union gm_mark_reference gm_mark_reference_t
 

a reference to a mark, or a free entry. The reference is used to validate the mark. That mark is considered valid if and only if (set->reference[mark->tag] == mark).


Function Documentation

GM_ENTRY_POINT gm_status_t gm_mark struct gm_mark_set   set,
gm_mark_t *    m
 

gm_mark() adds `*MARK' to SET. Requires O(constant) time if the mark set has preallocated resources for the mark. Otherwise, requires O(constant) average time.

Return values:
GM_SUCCESS  Operation completed successfully.
Parameters:
set  (IN) Handle to the GM mark set.
m 
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT int gm_mark_is_valid struct gm_mark_set   set,
gm_mark_t *    m
 

gm_mark_is_valid() returns nonzero value if `*MARK' is in SET. Requires O(constant) time.

Return values:
int 
Parameters:
set  (IN) Handle to the GM mark set.
m 
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT void gm_unmark struct gm_mark_set   set,
gm_mark_t *    m
 

gm_unmark() removes `*MARK' from SET. Requires O(constant) time.

Parameters:
set  (IN) Handle to the GM mark set.
m 
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT gm_status_t gm_create_mark_set struct gm_mark_set **    msp,
unsigned long    cnt
 

gm_create_mark_set() returns a pointer to a new mark set at SET with enough preallocated resources to support INIT_COUNT. Returns GM_SUCCESS on success. Requires time comparable to malloc().

Return values:
GM_SUCCESS  Operation completed successfully.
Parameters:
msp  (IN) Handle to the GM mark set.
cnt 
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT void gm_destroy_mark_set struct gm_mark_set   set
 

gm_destroy_mark_set() frees all resources associated with mark set `*SET'. Requires time comparable to free().

Parameters:
set  (IN) Handle to the GM mark set.
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT void gm_unmark_all struct gm_mark_set   set
 

gm_unmark_all() unmarks all marks for the mark set, freeing all but the initial number of preallocated mark references.

Removes all marks from SET. Requires O(constant) time.

Parameters:
set  (IN) Handle to the GM mark set.
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)


Generated on Mon Nov 3 15:39:26 2003 for GM by doxygen1.2.15