windows-nt/Source/XPSP1/NT/net/qos/pclass/gpc/handfact.c

/*
 *  handfact.c
 *
 *  author:	John R. Douceur
 *  date:	26 January 1998
 *
 *  This source file provides functions that implement assignment, release, and
 *  dereferencing operations with a handle_factory.  The code is object-oriented
 *  C, transliterated from a C++ implementation.
 *
 *  The handle factory is a component that generates and validates handles.  It
 *  is intended to be used in a software module that provides client software
 *  modules with means to refer to information structures contained within the
 *  provider.  While such a means could simply be a pointer, this would not
 *  enable the deletion of the information structures without explicitly
 *  notifying the clients of such deletion.  Unlike pointers, the handles
 *  generated by the handle factory can be examined (by the handle factory)
 *  to determine their validity.
 *
 *  Handles can be invalidated in one of two ways.  The handle can be released
 *  by calling the release_HF_handle() function, indicating to the handle
 *  factory that the handle is no longer necessary and that future requests
 *  to dereference this handle should be met with a null pointer.  Alternately,
 *  the handle can be revoked by the handle factory; this will happen unter two
 *  circumstances.  If a large number of handles (more than four billion) are
 *  issued and subsequently released, it becomes necessary to reuse portions of
 *  the handle space for future assignments; under these circumstances, very
 *  old handles will be revoked well before this recycling occurs, to give the
 *  holders of those handles ample opportunity to notice that their handles
 *  have become invalid and to request new handles.  The other situation in
 *  which revokation can occur is if the amount of available memory becomes
 *  too small to allocate additional space to expand the handle database; then,
 *  if the assignment of a new handle is requested, the least-recently-assigned
 *  handle will be revoked to make room for the new request.
 *
 *  Use of the handle factory in a multi-threaded environment requires a lock.
 *  This lock must be taken by a single thread for the execution of either
 *  assign_HF_handle() or release_HF_handle().  Use of dereference_HF_handle()
 *  does not require taking a lock, since synchronization is handled internally
 *  through careful sequencing of read and write operations.
 *
 *  None of the code or comments in this file need to be understood by writers
 *  of client code; all explanatory information for clients is found in the
 *  associated header file, handfact.h.
 *
 */

#include "gpcpre.h"

/*
 *  There are a number of aspects to the handle factory that must be understood
 *  by anyone wishing to modify this code.  The description in this comment
 *  block is intended to provide a progressive overview of the handle factory.
 *
 *  The basic system comprises a table of entries.  Each assigned handle
 *  corresponds to a single, unique entry, as determined by the handle value
 *  modulo the table size.  A handle is validated by comparing the handle value
 *  to the stored handle value in the entry.  The unassigned entries are kept
 *  on a list; when an entry is released (or revoked), it is put on the tail of
 *  the list, and when an entry is needed for an assignment, it is taken from
 *  the head of the list.
 *
 *  If there are no unassigned entries in the table when a new handle is
 *  requested, a new table of twice the size is allocated, and all assigned
 *  handles are relocated to the new table.  All unassigned handles in the new
 *  table are placed on the unassigned list.
 *
 *  As handles are released, the space required for handle entries is reduced.
 *  The table can be contracted into a table of half the size if no two assigned
 *  handles will yield the same entry address.  Two handles which will yield
 *  the same entry address in a half-size table are called a pair, and the
 *  number of such pairs is tracked in the variable pair_count, which must be
 *  zero in order to contract the table.  In order to minimize the number of
 *  pairs in the table, there are actually two lists of unassigned entries.
 *  Assigning an entry from the primary list will not increase the pair count,
 *  whereas assigning an entry from the secondary list will increase the pair
 *  count.  Thus, assignments are always made from the primary list, if it is
 *  not empty.
 *
 *  Assigned handles are also kept on a list, in order of assignment.  If it
 *  becomes necessary to revoke a handle to make room for another, the oldest
 *  handle will be revoked, and it will be found at the head of this list.
 *
 */

// This macro allocates an array of HFEntry structures.  The size of the array
// is provided as an argument to the macro.
//
//#define NEW_HFEntry_array(array_size) \
//	((HFEntry *)malloc(array_size * sizeof(HFEntry)))
#define NEW_HFEntry_array(_a,array_size) \
	GpcAllocMem(&_a,array_size * sizeof(HFEntry), HandleFactoryTag)

// This macro allocates an array of integers.  The size of the array is
// provided as an argument to the macro.
//
//#define NEW_int_array(array_size) \
//	((int *)malloc(array_size * sizeof(int)))
#define NEW_int_array(_a,array_size) \
	GpcAllocMem(&_a,array_size * sizeof(int), HandleFactoryTag)

/*
 *  Following are prototypes for static functions that are used internally by
 *  the handle factory routines.
 *
 */

// This function doubles the size of the table in which the handles and pointers
// are stored.  It is called by assign_HF_handle() when there is insufficient
// space in the table to assign the newly requested handle.  If the expansion
// is successful, the function returns a value of 0.  If the expansion fails
// (due, for example, to an inability to allocate memory), the function returns
// a value of 1.
//
int expand_HF_table(
	HandleFactory *hfact);

// This function halves the size of the table in which the handles and pointers
// are stored.  In order to reduce the amount of space consumed by the handle
// factory, this function is called called by release_HF_handle() and
// revoke_ancient_HF_handles() when they determine that the table can and should
// be contracted.  The table can be contracted when pair_count == 0 and
// table_size > 2.  However, the table may not be contracted then, because
// hysteresis is employed both to keep the mean assignment and release times
// constant and to minimize the allocation chatter of rapidly expanding and
// contracting the table.  If the contraction is successful, the function
// returns a value of 0.  If the contraction fails, the function returns a
// value of 1.
//
int contract_HF_table(
	HandleFactory *hfact);

// This function revokes handles that are between handle_base and handle_base
// + 2 * HANDLE_RANGE_STEP - 1, inclusive.  It then increments the value of
// handle_base by HANDLE_RANGE_STEP.  Suspended handles will be revoked one
// revokation pass later than non-suspended handles.
//
void revoke_ancient_HF_handles(
	HandleFactory *hfact);

// Every entry is on one of three lists, and the heads and tails of these lists
// are maintained in the entry_list[] array.  The index of this array is given
// by the following three manifest constants.
//
#define LD_PRIMARY 0       // first list from which to select an entry to assign
#define LD_SECONDARY 1    // second list from which to select an entry to assign
#define LD_ASSIGNED 2    // list of assigned entries, in order of assignment age

// When the handle space is recycled, there is a danger of handle collisions.
// In order to substantially reduce the likelihood of these collisions, very
// old handles are revoked well before their recycling begins, to give the
// holders of these handles ample opportunity to notice that their handles
// have become invalid and to request new handles.  Thus, handles are revoked
// when they become more than MAX_HANDLE_RANGE less than the currently generated
// handles.  To reduce overhead, revokations are performed in batches of size
// determined by HANDLE_RANGE_STEP.
//
// A handle may be suspended by incrementing the handle value by
// HANDLE_RANGE_STEP.  This causes the comparison in dereference_HF_handle() to
// fail, so the handle is judged to be invalid.  To reinstate the handle, the
// handle value is decremented by HANDLE_RANGE_STEP, returning the handle to its
// original value.  A handle that is suspended will be revoked one revokation
// pass later than it would have been if it hadn't been suspended.
//
#define HANDLE_RANGE_STEP ((HFHandle)0x20000000)
#define MAX_HANDLE_RANGE ((HFHandle)0x90000000)

// To keep the mean assignment and release times constant (and, indirectly, to
// minimize the allocation chatter of rapidly expanding and contracting the
// table), the table is not necessarily contracted as soon as possible.
// Hysteresis is employed to postpone the contraction until the computational
// cost of previous expansions and contractions is distributed over a sufficient
// number of assignment or release operations to maintain a constant cost per
// operation ratio.  The cost of each expansion is equal to the overhead of
// memory allocation and deallocation plus the cost to split each entry into
// two entries.  The cost of each contraction is equal to the overhead of
// memory allocation and deallocation plus the cost to merge each pair of
// entries into one entry.  The cost of memory allocation and deallocation is
// equal to ALLOCATION_COST times the mean cost of a single split or merge
// operation.  This value was determined by empirical measurement.
//
#define ALLOCATION_COST 12

// Since this is not C++, the HandleFactory structure is not self-constructing;
// therefore, the following constructor code must be called on the HandleFactory
// structure after it is allocated.  If the construction is successful, the
// function returns a value of 0.  If the construction fails (due, for example,
// to an inability to allocate memory), the function returns a value of 1.
//
int
constructHandleFactory(
	HandleFactory *hfact)
{
	// The table size is initially set to 2, and it will never be smaller.
	hfact->table_size = 2;
	// Allocate space for the initial table.
	NEW_HFEntry_array(hfact->entries,hfact->table_size);
	if (hfact->entries == 0)
	{
		// Memory could not be allocated for the array of entries created by
		// the constructor.  Therefore, we return an indication of failure to
		// the client.
		return 1;
	}
	hfact->verifier0 = 0;   // the verifiers are initialized with the same value
	hfact->verifier1 = 0;   // the verifiers are initialized with the same value
	hfact->handle_base = 0;                         // handles will start with 0
	hfact->population = 0;                      // no handles initially assigned
	hfact->pair_count = 0;                // since no assigned handles, no pairs
	hfact->hysteresis_debt = 0;
	// Initialize the two entries that are initially allocated.  Both are marked
	// as unassigned; the larger value (2) is put on the secondary list, and the
	// smaller value (1) on the secondary list.  Record 0 contains an initial
	// handle value of 2 instead of 0 because a handle value of 0 is reserved.
	hfact->entries[0].handle = hfact->handle_base + hfact->table_size;
	hfact->entries[0].next_handle = hfact->handle_base + hfact->table_size;
	hfact->entries[0].reference = 0;
	hfact->entries[0].next_entry = &hfact->entry_list[LD_SECONDARY];
	hfact->entries[0].prev_entry = &hfact->entry_list[LD_SECONDARY];
	hfact->entries[1].handle = hfact->handle_base + 1;
	hfact->entries[1].next_handle = hfact->handle_base + 1;
	hfact->entries[1].reference = 0;
	hfact->entries[1].next_entry = &hfact->entry_list[LD_PRIMARY];
	hfact->entries[1].prev_entry = &hfact->entry_list[LD_PRIMARY];
	// Initialize the primary list.  This list initially contains entry 1.
	hfact->entry_list[LD_PRIMARY].handle = 0;
	hfact->entry_list[LD_PRIMARY].next_handle = 0;
	hfact->entry_list[LD_PRIMARY].reference = 0;
	hfact->entry_list[LD_PRIMARY].next_entry = &hfact->entries[1];
	hfact->entry_list[LD_PRIMARY].prev_entry = &hfact->entries[1];
	// Initialize the secondary list.  This list initially contains entry 0.
	hfact->entry_list[LD_SECONDARY].handle = 0;
	hfact->entry_list[LD_SECONDARY].next_handle = 0;
	hfact->entry_list[LD_SECONDARY].reference = 0;
	hfact->entry_list[LD_SECONDARY].next_entry = &hfact->entries[0];
	hfact->entry_list[LD_SECONDARY].prev_entry = &hfact->entries[0];
	// Initialize the assigned list.  This list initially is empty.
	hfact->entry_list[LD_ASSIGNED].handle = 0;
	hfact->entry_list[LD_ASSIGNED].next_handle = 0;
	hfact->entry_list[LD_ASSIGNED].reference = 0;
	hfact->entry_list[LD_ASSIGNED].next_entry = &hfact->entry_list[LD_ASSIGNED];
	hfact->entry_list[LD_ASSIGNED].prev_entry = &hfact->entry_list[LD_ASSIGNED];
	// Reduce handle_base by HANDLE_RANGE_STEP so that suspended handles will
	// not slip through revokation.
	hfact->handle_base -= HANDLE_RANGE_STEP;
	// return an indication of success to the client.
	return 0;
}

// Since this is not C++, the HandleFactory structure is not self-destructing;
// therefore, the following destructor code must be called on the HandleFactory
// structure before it is deallocated.
//
void
destructHandleFactory(
	HandleFactory *hfact)
{
	// Free the space consumed by the table of handles.
	GpcFreeMem(hfact->entries, HandleFactoryTag);
}

// This function generates a new handle value, associates the handle value with
// the provided reference pointer, and returns the handle value.  Barring
// highly unusual circumstances, this handle will remain valid until it is
// explicitly released by a call to release_HF_handle().  However, there is no
// guarantee that the handle will persist for an arbitrary duration; it may
// become necessary for the handle factory to revoke the handle under some
// circumstances, particularly when the handle becomes very old or when memory
// becomes scarce.
//
// The assign_HF_handle() function will never return a handle value of zero.
// Thus, the client program is free to use a zero handle value as an escape
// indicator, if desired.
//
// In a multi-threaded environment, a single thread must take a lock prior to
// calling this function, and this must be the same lock taken before calling
// release_HF_handle().
//
HFHandle
assign_HF_handle(
	HandleFactory *hfact,
	void *reference)
{
	int list;
	HFEntry *entry;
	volatile HFEntry *seq_entry;                // volatile to ensure sequencing
	HFHandle handle;
	HFHandle handle_range;

	if (hfact->population >= hfact->table_size)
	{
		// All entries in the table are assigned, so it is necessary to
		// increase the table size.
		int expansion_failure = expand_HF_table(hfact);
		if (expansion_failure)
		{
            //
            // just fail
            //

            return 0;
#if 0

            // Expanding the table failed, presumably due to inability to
			// allocate sufficient memory.  So, instead, we revoke the least-
			// recently assigned handle.  First, remove the entry from the
			// assigned list and place it on the secondary list.
			entry = hfact->entry_list[LD_ASSIGNED].next_entry;
			entry->next_entry->prev_entry = &hfact->entry_list[LD_ASSIGNED];
			hfact->entry_list[LD_ASSIGNED].next_entry = entry->next_entry;
			entry->next_entry = &hfact->entry_list[LD_SECONDARY];
			entry->prev_entry = hfact->entry_list[LD_SECONDARY].prev_entry;
			hfact->entry_list[LD_SECONDARY].prev_entry->next_entry = entry;
			hfact->entry_list[LD_SECONDARY].prev_entry = entry;
			// Then, invalidate the handle.  The order of the operations is
			// important to correct multi-threaded operation.
			seq_entry = entry;
			seq_entry->handle = entry->next_handle;   // first invalidate handle
			seq_entry->reference = 0;                    // then clear reference
			// Decrement the pair count and population, so that when they are
			// incremented in the code below, they will have correct values.
			hfact->pair_count--;
			hfact->population--;
#endif
		}
	}
	// At this point, there is at least one available entry.  If there is any
	// entry on the primary list, it should be selected.
	list = LD_PRIMARY;
	if (hfact->entry_list[LD_PRIMARY].next_entry ==
		&hfact->entry_list[LD_PRIMARY])
	{
		// The primary list is empty, so we take from the secondary list.  By
		// definition, this will increase the pair count.
		list = LD_SECONDARY;
		hfact->pair_count++;
	}
	// Remove the entry from the head of the appropriate list and place it on
	// the assigned list.
	entry = hfact->entry_list[list].next_entry;
	handle = entry->handle;
	entry->next_entry->prev_entry = entry->prev_entry;
	entry->prev_entry->next_entry = entry->next_entry;
	entry->next_entry = &hfact->entry_list[LD_ASSIGNED];
	entry->prev_entry = hfact->entry_list[LD_ASSIGNED].prev_entry;
	hfact->entry_list[LD_ASSIGNED].prev_entry->next_entry = entry;
	hfact->entry_list[LD_ASSIGNED].prev_entry = entry;
	// Set the reference pointer to that provided as an argument.
	entry->reference = reference;
	// The next handle for this entry will be greater by the table size.  It
	// is important to set this value in this routine because unequal values of
	// handle and next_handle indicate an assigned entry.
	entry->next_handle = handle + hfact->table_size;
	if (entry->next_handle == 0)
	{
		// The handle value has wrapped around back to zero; however, zero is
		// a reserved value, so we instead set the next handle to the subsequent
		// legal value, which is the table size.
		entry->next_handle = hfact->table_size;
	}
	// The population has increased by one.
	hfact->population++;
	// We're being tricky with unsigned integer math here.  We revoke ancient
	// handles if the value of the handle we are currently issuing is greater
	// than the handle base by more than MAX_HANDLE_RANGE, modulo the size of
	// the handle space.  The modulo is implicit.
	handle_range = handle - hfact->handle_base;
	if (handle_range > MAX_HANDLE_RANGE)
	{
		revoke_ancient_HF_handles(hfact);
	}
	// This assignment operation decreases the hysteresis debt.
	if (hfact->hysteresis_debt > 0)
	{
		hfact->hysteresis_debt--;
	}
	// Return the newly assigned handle.
	return handle;
}

// This function releases a handle, indicating that further attempts to
// dereference the handle should result in a null pointer value rather than the
// pointer value that was originally assigned to the handle.  The handle factory
// checks the validity of the handle and returns a corresponding status code.
// If the handle is currently assigned, then it is released, and the function
// returns a value of 0.  If the handle is not currently assigned, the function
// aborts and returns a value of 1.
//
// In a multi-threaded environment, a single thread must take a lock prior to
// calling this function, and this must be the same lock taken before calling
// assign_HF_handle().
//
int
release_HF_handle(
	HandleFactory *hfact,
	HFHandle handle)
{
	int entry_index;
	HFEntry *entry;
	HFEntry *other_entry;
	int list;
	HFHandle adjusted_next_handle;
	HFHandle adjusted_other_next_handle;
	volatile HFEntry *seq_entry;                // volatile to ensure sequencing

	// Compute the index of the entry by taking the handle value modulo the
	// table size.  Since the table size is a power of two, we can simply
	// subtract one to produce a mask and then conjoin the mask with the
	// handle value.
	entry_index = handle & hfact->table_size - 1;
	entry = &hfact->entries[entry_index];
	if ((entry->handle != handle && entry->handle != handle + HANDLE_RANGE_STEP)
		|| entry->handle == entry->next_handle)
	{
		// Either the indexed entry does not refer to the provided handle nor to
		// the provided handle's suspension value, or the entry is unassigned.
		// In any of these cases, abort and return an error code to the client.
		return 1;
	}
	// The "other entry" is the entry that would have to be merged with the
	// indexed entry if the table size were to be contracted in half.
	other_entry = &hfact->entries[entry_index ^ hfact->table_size / 2];
	if (other_entry->handle == other_entry->next_handle)
	{
		// We're being tricky with unsigned integer math here.  Before comparing
		// the two next handles, we subtract from each the value of handle_base,
		// modulo the size of the handle space (the modulo is implicit).  This
		// allows the effective comparison of their logical acyclic values
		// rather than their actual cyclic values.
		adjusted_next_handle = entry->next_handle - hfact->handle_base;
		adjusted_other_next_handle =
			other_entry->next_handle - hfact->handle_base;
		if (adjusted_other_next_handle < adjusted_next_handle)
		{
			// The other entry is unassigned and has a smaller handle value
			// than the indexed entry.  Thus, the other entry should be moved
			// from the secondary list to the primary list, and the indexed
			// entry should be placed on the secondary list.
			other_entry->next_entry->prev_entry = other_entry->prev_entry;
			other_entry->prev_entry->next_entry = other_entry->next_entry;
			other_entry->next_entry = &hfact->entry_list[LD_PRIMARY];
			other_entry->prev_entry = hfact->entry_list[LD_PRIMARY].prev_entry;
			hfact->entry_list[LD_PRIMARY].prev_entry->next_entry = other_entry;
			hfact->entry_list[LD_PRIMARY].prev_entry = other_entry;
			list = LD_SECONDARY;
		}
		else
		{
			// The other entry is unassigned and has a larger handle value
			// than the indexed entry.  Thus, the indexed entry should be
			// placed on the secondary list.
			list = LD_PRIMARY;
		}
	}
	else
	{
		// The other entry is assigned.  Thus, the indexed entry should be
		// placed on the secondary list.  Also, since the two entries were
		// both assigned, they formed a pair.  Since we are releasing one of
		// them, the pair count drops by one.
		list = LD_SECONDARY;
		hfact->pair_count--;
	}
	// Remove the entry from the assigned list and place it on the
	// appropriate list.
	entry->next_entry->prev_entry = entry->prev_entry;
	entry->prev_entry->next_entry = entry->next_entry;
	entry->next_entry = &hfact->entry_list[list];
	entry->prev_entry = hfact->entry_list[list].prev_entry;
	hfact->entry_list[list].prev_entry->next_entry = entry;
	hfact->entry_list[list].prev_entry = entry;
	// Invalidate the handle.  The order of the operations is important to
	// correct multi-threaded operation.
	seq_entry = entry;
	seq_entry->handle = entry->next_handle;           // first invalidate handle
	seq_entry->reference = 0;                            // then clear reference
	// The population has decreased by one.
	hfact->population--;
	// This release operation decreases the hysteresis debt.
	if (hfact->hysteresis_debt > 0)
	{
		hfact->hysteresis_debt--;
	}
	// To contract the table, there must be no pairs, because otherwise two
	// assigned handles would yield the same entry index and thereby conflict.
	// Furthermore, the table size must be greater than 2, because much of the
	// handle factory code assumes that the table is at least of size 2.  In
	// addition to these strict requirements, hysteresis is employed both to
	// keep the mean assignment and release times constant and to minimize the
	// allocation chatter of rapidly expanding and contracting the table.  Only
	// if the hysteresis debt is zero will the table be contracted.
	if (hfact->pair_count == 0 && hfact->table_size > 2 &&
		hfact->hysteresis_debt == 0)
	{
		contract_HF_table(hfact);
		// Note that we ignore the return code.  If the contraction is
		// unsuccessful, we just continue as usual.  There is no real harm in
		// not contracting the table, except that we consume more space than
		// necessary.
	}
	// return an indication of success to the client.
	return 0;
}

// This function suspends a handle, indicating that further attempts to
// dereference the handle should result in a null pointer value rather than the
// pointer value that was originally assigned to the handle, unless and until
// reinstate_HF_handle() is called on the handle value.  The handle factory
// checks the validity of the handle and returns a corresponding status code.
// If the handle is currently assigned and not suspended, then it is suspended,
// and the function returns a value of 0.  If the handle is not currently
// assigned or has already been suspended, the function aborts and returns a
// value of 1.
//
// In a multi-threaded environment, a single thread must take a lock prior to
// calling this function, and this must be the same lock taken before calling
// assign_HF_handle(), release_HF_handle(), and reinstate_HF_handle().
//
int
suspend_HF_handle(
	HandleFactory *hfact,
	HFHandle handle)
{
	int entry_index;
	HFEntry *entry;

	// Compute the index of the entry by taking the handle value modulo the
	// table size.  Since the table size is a power of two, we can simply
	// subtract one to produce a mask and then conjoin the mask with the
	// handle value.
	entry_index = handle & hfact->table_size - 1;
	entry = &hfact->entries[entry_index];
	if (entry->handle != handle || entry->handle == entry->next_handle)
	{
		// Either the indexed entry does not refer to the provided handle, or
		// the entry is unassigned.  In either case, abort and return an error
		// code to the client.
		return 1;
	}
	// Suspend the handle.
	entry->handle += HANDLE_RANGE_STEP;
	// This suspension operation decreases the hysteresis debt.
	if (hfact->hysteresis_debt > 0)
	{
		hfact->hysteresis_debt--;
	}
	// return an indication of success to the client.
	return 0;
}

// This function reinstates a suspended handle, indicating that further attempts
// to dereference the handle should result in the pointer value that was
// originally assigned to the handle, rather than the null pointer value to
// which a suspended handle dereferences.  The handle factory checks the
// validity of the handle and returns a corresponding status code. If the handle
// is currently assigned and suspended, then it is reinstated, and the function
// returns a value of 0.  If the handle is not currently assigned or is not
// suspended, the function aborts and returns a value of 1.
//
// In a multi-threaded environment, a single thread must take a lock prior to
// calling this function, and this must be the same lock taken before calling
// assign_HF_handle(), release_HF_handle(), and suspend_HF_handle().
//
int
reinstate_HF_handle(
	HandleFactory *hfact,
	HFHandle handle)
{
	int entry_index;
	HFEntry *entry;

	// Compute the index of the entry by taking the handle value modulo the
	// table size.  Since the table size is a power of two, we can simply
	// subtract one to produce a mask and then conjoin the mask with the
	// handle value.
	entry_index = handle & hfact->table_size - 1;
	entry = &hfact->entries[entry_index];
	if (entry->handle != handle + HANDLE_RANGE_STEP ||
		entry->handle == entry->next_handle)
	{
		// Either the indexed entry does not refer to the provided handle's
		// suspension value, or the entry is unassigned.  In either case, abort
		// and return an error code to the client.
		return 1;
	}
	// Reinstate the handle.
	entry->handle -= HANDLE_RANGE_STEP;
	// This reinstatement operation decreases the hysteresis debt.
	if (hfact->hysteresis_debt > 0)
	{
		hfact->hysteresis_debt--;
	}
	// return an indication of success to the client.
	return 0;
}

// This function validates a handle and returns either the associated pointer
// (if the handle is valid) or a null pointer value (if the handle is invalid).
// If the handle has not been released but a null value is returned, then the
// handle has been revoked by the handle factory.  This is expected to be a
// highly unusual occurrence; however, since it can happen, any program that
// employs the handle factory must have some auxiliary mechanism for retrieving
// the desired pointer information.  Once the pointer is retrieved through this
// (presumably expensive) auxiliary means, a new handle can be reassigned to
// the pointer by another call to assign_HF_handle().
//
// Even in a multi-threaded environment, it is not necessary to take a lock
// prior to calling this function.  Careful sequencing of read and write
// operations inside the handle factory code obviates the need to explicitly
// lock the data structure for dereferencing handles.
//
void *
dereference_HF_handle(
	HandleFactory *hfact,
	HFHandle handle)
{
	HFHandle entry_handle;
	void *reference;
	//int verifier;
	int entry_index;
	/*volatile*/ HFEntry *entry;                    // volatile to ensure sequencing

	// This loop spins until the verifier variables begin and end a pass of
	// the loop with the same value. There is an extremely short sequence
	// of instructions in the expand and contract routines that modifies the
	// values of the entries and table_size variables, and these modifications
	// are bracketed by increments of the verifier variables in the reverse
	// order as they are here read.  As long as the verifiers have the same
	// value, then entries and table_size are in a consistent state.  This loop
	// should very rarely be executed more than once, since the modification in
	// the other routines is so short.
	do
	{
		//verifier = hfact->verifier1;
		// Compute the index of the entry by taking the handle value modulo the
		// table size.  Since the table size is a power of two, we can simply
		// subtract one to produce a mask and then conjoin the mask with the
		// handle value.
		entry_index = handle & hfact->table_size - 1;
		entry = &hfact->entries[entry_index];
		// Get local copies of the reference pointer and handle value.  The
		// order of the operations is important to correct multi-threaded
		// operation.
		reference = entry->reference;                     // first get reference
		entry_handle = entry->handle;       // then get handle to check validity
	}	while (0 /*verifier != hfact->verifier0*/);
	if (entry_handle == handle)
	{
		// The stored handle matches the provided handle, so the latter is
		// valid.  We thus return the reference pointer.
		return reference;
	}
	else
	{
		// The stored handle does not match the provided handle, so the latter
		// is invalid.  We thus return a null pointer.
		return 0;
	}
}



void *
dereference_HF_handle_with_cb(
	HandleFactory *hfact,
	HFHandle handle,
    ULONG    offset)
{
	HFHandle entry_handle;
	void *reference;
	//int verifier;
	int entry_index;
	/*volatile*/ HFEntry *entry;                    // volatile to ensure sequencing

	// This loop spins until the verifier variables begin and end a pass of
	// the loop with the same value. There is an extremely short sequence
	// of instructions in the expand and contract routines that modifies the
	// values of the entries and table_size variables, and these modifications
	// are bracketed by increments of the verifier variables in the reverse
	// order as they are here read.  As long as the verifiers have the same
	// value, then entries and table_size are in a consistent state.  This loop
	// should very rarely be executed more than once, since the modification in
	// the other routines is so short.
	do
	{
		//verifier = hfact->verifier1;
		// Compute the index of the entry by taking the handle value modulo the
		// table size.  Since the table size is a power of two, we can simply
		// subtract one to produce a mask and then conjoin the mask with the
		// handle value.
		entry_index = handle & hfact->table_size - 1;
		entry = &hfact->entries[entry_index];
		// Get local copies of the reference pointer and handle value.  The
		// order of the operations is important to correct multi-threaded
		// operation.

        if ((entry->reference) && (entry->handle == handle)) {

            ASSERT(((PCLASSIFICATION_BLOCK)entry->reference)->NumberOfElements > offset);
            reference = (void *)((PCLASSIFICATION_BLOCK)entry->reference)->arpBlobBlock[offset];
            TRACE(CLASSIFY, entry->reference, reference, "dereference_HF_handle_with_cb");

            return reference;

        } else {

            reference = 0;
            return 0;

        }

	}	while (0 /*verifier != hfact->verifier0*/);

}




#ifdef _TEST_HANDFACT

// This is a test routine that simply verifies the internal valididy of the
// handle factory's data structures.  By defining the constant _TEST_HANDFACT,
// this routine will be compiled and available to the client code.  It can be
// called at any time, unless running in a multi-threaded environment, in which
// case the caller must first take the same lock used for assign_HF_handle()
// and release_HF_handle.  If the routine returns any value other than zero,
// then the internal lists of records are in an inconsistent state.
//
int
verify_HF_lists(
	HandleFactory *hfact)
{
	int entry_count[3];
	int list;
	HFEntry *entry;
	for (list = 0; list < 3; list++)
	{
		entry_count[list] = 0;
		entry = &hfact->entry_list[list];
		do
		{
			entry_count[list]++;
			if (entry->next_entry->prev_entry != entry)
			{
				return 1;
			}
			entry = entry->next_entry;
		}	while (entry != &hfact->entry_list[list]);
		entry_count[list]--;
	}
	if (entry_count[2] != hfact->population)
	{
		return 2;
	}
	if (entry_count[0] + entry_count[2] - 2 * hfact->pair_count !=
		entry_count[1])
	{
		return 3;
	}
	if (entry_count[0] + entry_count[1] + entry_count[2] != hfact->table_size)
	{
		return 4;
	}
	return 0;
}

#endif /* _TEST_HANDFACT */

// This function doubles the size of the table in which the handles and pointers
// are stored.  It is called by assign_HF_handle() when there is insufficient
// space in the table to assign the newly requested handle.  If the expansion
// is successful, the function returns a value of 0.  If the expansion fails
// (due, for example, to an inability to allocate memory), the function returns
// a value of 1.
//
int expand_HF_table(
	HandleFactory *hfact)
{
	int double_size;
	HFEntry *new_entries;
	HFEntry *old_entries;
	HFEntry *old_entry;
	HFEntry *low_entry;
	HFEntry *high_entry;
	HFEntry *assigned_entry;
	HFEntry *secondary_entry;
	HFEntry *other_entry;
	HFHandle handle;
	HFHandle next_handle;
	HFHandle other_handle;
	void *reference;
	int other_entry_index;
	int index;

	// Expanded table is double the size of the old table.
	double_size = hfact->table_size * 2;
	// Allocate space for the expanded table.
	NEW_HFEntry_array(new_entries,double_size);
	if (new_entries == 0)
	{
		// Memory could not be allocated for the new array of entries.
		// Therefore, we return an indication of failure.
		return 1;
	}
	// Since we are doubling the table size, we will be treating one more bit
	// of each handle as a bit of the entry index.  The value of this bit
	// determines the index of the entry in the new table.  For each entry,
	// we have to determine the value of this bit and relocate the entry to
	// the indicated location.
	for (index = 0; index < hfact->table_size; index++)
	{
		old_entry = &hfact->entries[index];
		low_entry = &new_entries[index];
		high_entry = &new_entries[hfact->table_size + index];
		handle = old_entry->handle;
		next_handle = old_entry->next_handle;
		reference = old_entry->reference;
		// One of the two entries in the new table that correspond to the
		// indexed entry in the old table will have a next handle value equal
		// to the next handle value of the entry in the old table, and one will
		// have a handle value equal to the indexed entry's next handle plus
		// the old table size.
		other_handle = next_handle + hfact->table_size;
		if (other_handle == 0)
		{
			// The handle value has wrapped around back to zero; however, zero
			// is a reserved value, so we instead set the next handle to the
			// subsequent legal value, which is the new table size.
			other_handle = double_size;
		}
		if ((handle & hfact->table_size) == 0)
		{
			// The handle of the old entry has a zero in its next bit, so the
			// old entry will be located in the lower half of the new table.
			if ((next_handle & hfact->table_size) == 0)
			{
				// The next handle of the old entry has a zero in its next bit,
				// so this value will be the next handle for the lower entry
				// and the other next handle value will be the next handle
				// value for the higher entry.  The high entry handle is set
				// equal to its next handle because it is unassigned.
				high_entry->handle = other_handle;
				high_entry->next_handle = other_handle;
				low_entry->next_handle = next_handle;
			}
			else
			{
				// The next handle of the old entry has a zero in its next bit,
				// so this value will be the next handle for the higher entry
				// and the other next handle value will be the next handle
				// value for the lower entry.  The high entry handle is set
				// equal to its next handle because it is unassigned.
				high_entry->handle = next_handle;
				high_entry->next_handle = next_handle;
				low_entry->next_handle = other_handle;
			}
			// The high entry is unassigned, so set its reference to null.
			// Copy the information from the old entry to the low entry.
			// Remove the old entry from the assigned list, and replace it
			// with the low entry.
			high_entry->reference = 0;
			low_entry->handle = handle;
			low_entry->reference = reference;
			old_entry->next_entry->prev_entry = low_entry;
			old_entry->prev_entry->next_entry = low_entry;
			low_entry->next_entry = old_entry->next_entry;
			low_entry->prev_entry = old_entry->prev_entry;
		}
		else
		{
			// The handle of the old entry has a one in its next bit, so the
			// old entry will be located in the higher half of the new table.
			if ((next_handle & hfact->table_size) == 0)
			{
				// The next handle of the old entry has a zero in its next bit,
				// so this value will be the next handle for the lower entry
				// and the other next handle value will be the next handle
				// value for the higher entry.  The low entry handle is set
				// equal to its next handle because it is unassigned.
				high_entry->next_handle = other_handle;
				low_entry->handle = next_handle;
				low_entry->next_handle = next_handle;
			}
			else
			{
				// The next handle of the old entry has a zero in its next bit,
				// so this value will be the next handle for the higher entry
				// and the other next handle value will be the next handle
				// value for the lower entry.  The low entry handle is set
				// equal to its next handle because it is unassigned.
				high_entry->next_handle = next_handle;
				low_entry->handle = other_handle;
				low_entry->next_handle = other_handle;
			}
			// The low entry is unassigned, so set its reference to null.
			// Copy the information from the old entry to the high entry.
			// Remove the old entry from the assigned list, and replace it
			// with the high entry.
			low_entry->reference = 0;
			high_entry->handle = handle;
			high_entry->reference = reference;
			old_entry->next_entry->prev_entry = high_entry;
			old_entry->prev_entry->next_entry = high_entry;
			high_entry->next_entry = old_entry->next_entry;
			high_entry->prev_entry = old_entry->prev_entry;
		}
	}
	// All of the unassigned entries in the new table will be placed on the
	// secondary list.  We loop through the assigned list and place the
	// unassigned entry corresponding each assigned entry onto the secondary
	// list.  Doing the list assignment in this manner tends to approximately
	// sort the secondary list according to handle value, since the assigned
	// list is sorted according to assignment order, and this approximately
	// correlates to the handle value.
	assigned_entry = hfact->entry_list[LD_ASSIGNED].next_entry;
	secondary_entry = &hfact->entry_list[LD_SECONDARY];
	while (assigned_entry != &hfact->entry_list[LD_ASSIGNED])
	{
		other_entry_index =
			assigned_entry->handle + hfact->table_size & double_size - 1;
		other_entry = &new_entries[other_entry_index];
		secondary_entry->next_entry = other_entry;
		other_entry->prev_entry = secondary_entry;
		secondary_entry = other_entry;
		assigned_entry = assigned_entry->next_entry;
	}
	// Wrap up lists by connecting in tails.
	secondary_entry->next_entry = &hfact->entry_list[LD_SECONDARY];
	hfact->entry_list[LD_SECONDARY].prev_entry = secondary_entry;
	// This expansion increases the hysteresis debt by the cost of one set of
	// allocation and deallocation operations plus the cost of splitting each
	// entry into two entries.
	hfact->hysteresis_debt += ALLOCATION_COST + hfact->table_size;
	// Save a pointer to the old entry table so that it can be deallocated.
	old_entries = hfact->entries;
	// Note that we have not modified the handle, next_handle, or reference
	// fields of any entries in the old table.  Therefore, any calls to the
	// dereference_HF_handle() routine that may have been made by other threads
	// during the above operations would have been performed successfully.
	// We are now about to increase the table size and update the entries
	// variable to point to the new table.  These operations must be performed
	// atomically in order for the dereference routine to perform correctly.
	// We thus bracket the operations with increments to the verifier variables.
	// When the verifiers have the same value, the table_size and entries
	// variables are in a consistent state.  This is checked by the dereference
	// routine.
	hfact->verifier0++;                                // begin critical section
	hfact->entries = new_entries;
	hfact->table_size = double_size;
	hfact->verifier1 = hfact->verifier0;                 // end critical section
	// Deallocate the old table.
	GpcFreeMem(old_entries, handleFactoryTag);
	// Since the new table was created by expanding a half-size table, the pair
	// count must be zero.
	hfact->pair_count = 0;
	// return an indication of success.
	return 0;
}

// This function halves the size of the table in which the handles and pointers
// are stored.  In order to reduce the amount of space consumed by the handle
// factory, this function is called called by release_HF_handle() and
// revoke_ancient_HF_handles() when they determine that the table can and should
// be contracted.  The table can be contracted when pair_count == 0 and
// table_size > 2.  However, the table may not be contracted then, because
// hysteresis is employed both to keep the mean assignment and release times
// constant and to minimize the allocation chatter of rapidly expanding and
// contracting the table.  If the contraction is successful, the function
// returns a value of 0.  If the contraction fails, the function returns a
// value of 1.
//
int contract_HF_table(
	HandleFactory *hfact)
{
	HFEntry *new_entries;
	HFEntry *old_entries;
	int *list;
	int half_size;
	int quarter_size;
	int index;
	HFEntry *high_entry1;
	HFEntry *high_entry0;
	HFEntry *low_entry1;
	HFEntry *low_entry0;
	HFEntry *new_entry1;
	HFEntry *new_entry0;
	HFHandle adjusted_high_next_handle1;
	HFHandle adjusted_low_next_handle1;
	HFHandle next_handle1;
	HFHandle adjusted_high_next_handle0;
	HFHandle adjusted_low_next_handle0;
	HFHandle next_handle0;
	HFHandle adjusted_new_handle0;
	HFHandle adjusted_new_handle1;
	HFEntry *entry;
	HFEntry *primary_entry;
	HFEntry *secondary_entry;

	// Contracted table is half the size of the old table.
	half_size = hfact->table_size / 2;
	quarter_size = half_size / 2;
	// Allocate space for the contracted table.
	NEW_HFEntry_array(new_entries,half_size);
	if (new_entries == 0)
	{
		// Memory could not be allocated for the new array of entries, so we
		// are ironically prevented from reducing the amount of memory that
		// the handle factory is consuming. Therefore, we return an indication
		// of failure.
		return 1;
	}
	// Allocate space for auxiliary array of list indicators
	NEW_int_array(list,half_size);
	if (list == 0)
	{
		// Memory could not be allocated for the auxiliary array, so again we
		// are ironically prevented from reducing the amount of memory that
		// the handle factory is consuming. Therefore, we return an indication
		// of failure.  First, however, we must free the memory allocated for
		// the new array of entries above.
		GpcFreeMem(new_entries, handleFactoryTag);
		return 1;
	}
	// Since we are halving the size of the table, it might seem reasonable to
	// loop through each index of the new table and merge the two corresponding
	// entries from the old table.  This is in fact what the following routine
	// does; however, it does it by looping through only half of the new indices
	// and processing two merges for each index.  It does this so that it can
	// then examine the two new entries to determine on which list to place each
	// of them.
	for (index = 0; index < quarter_size; index++)
	{
		// We're looking at four entries at once.  First we merge high_entry1
		// and low_entry1, and then we independently merge high_entry0 and
		// low_entry0.  After the two merges, we examine the results jointly.
		high_entry1 = &hfact->entries[half_size + quarter_size + index];
		high_entry0 = &hfact->entries[half_size + index];
		low_entry1 = &hfact->entries[quarter_size + index];
		low_entry0 = &hfact->entries[index];
		new_entry1 = &new_entries[quarter_size + index];
		new_entry0 = &new_entries[index];
		// When merging two entries, the next handle value for the combined
		// entry is equal to the larger next handle value of the two, minus
		// the new table size.  However, the determination of which is larger
		// must be made with respect to their logical acyclic values rather
		// than their actual cyclic values, so we subtract from each the value
		// of handle_base, modulo the size of the handle space.  The modulo is
		// implicit.
		adjusted_high_next_handle1 =
			high_entry1->next_handle - hfact->handle_base;
		adjusted_low_next_handle1 =
			low_entry1->next_handle - hfact->handle_base;
		next_handle1 = __max(adjusted_high_next_handle1,
			adjusted_low_next_handle1) + hfact->handle_base - half_size;
		// Since handle 1 is -- by definition -- in either the second or fourth
		// quarter of the table, there is no need to check for the reserved
		// value of zero.
		if (high_entry1->handle != high_entry1->next_handle)
		{
			// The high entry is assigned, so we copy its handle value and
			// reference pointer.  Also, we remove it from the assigned list
			// and replace it with the new entry.
			new_entry1->handle = high_entry1->handle;
			new_entry1->reference = high_entry1->reference;
			high_entry1->next_entry->prev_entry = new_entry1;
			high_entry1->prev_entry->next_entry = new_entry1;
			new_entry1->next_entry = high_entry1->next_entry;
			new_entry1->prev_entry = high_entry1->prev_entry;
		}
		else if (low_entry1->handle != low_entry1->next_handle)
		{
			// The low entry is assigned, so we copy its handle value and
			// reference pointer.  Also, we remove it from the assigned list
			// and replace it with the new entry.
			new_entry1->handle = low_entry1->handle;
			new_entry1->reference = low_entry1->reference;
			low_entry1->next_entry->prev_entry = new_entry1;
			low_entry1->prev_entry->next_entry = new_entry1;
			new_entry1->next_entry = low_entry1->next_entry;
			new_entry1->prev_entry = low_entry1->prev_entry;
		}
		else
		{
			// Neither entry is assigned, so we indicate an unassigned condition
			// in the new entry.
			new_entry1->handle = next_handle1;
			new_entry1->reference = 0;
			if (adjusted_high_next_handle1 < adjusted_low_next_handle1)
			{
				// The high entry next handle has a lesser value than the low
				// entry next handle, so the high entry must be on the primary
				// list.  We remove it from the primary list and replace it
				// with the new entry.
				high_entry1->next_entry->prev_entry = new_entry1;
				high_entry1->prev_entry->next_entry = new_entry1;
				new_entry1->next_entry = high_entry1->next_entry;
				new_entry1->prev_entry = high_entry1->prev_entry;
			}
			else
			{
				// The low entry next handle has a lesser value than the high
				// entry next handle, so the low entry must be on the primary
				// list.  We remove it from the primary list and replace it
				// with the new entry.
				low_entry1->next_entry->prev_entry = new_entry1;
				low_entry1->prev_entry->next_entry = new_entry1;
				new_entry1->next_entry = low_entry1->next_entry;
				new_entry1->prev_entry = low_entry1->prev_entry;
			}
		}
		// Set the next handle for the new entry.
		new_entry1->next_handle = next_handle1;
		// When merging two entries, the next handle value for the combined
		// entry is equal to the larger next handle value of the two, minus
		// the new table size.  However, the determination of which is larger
		// must be made with respect to their logical acyclic values rather
		// than their actual cyclic values, so we subtract from each the value
		// of handle_base, modulo the size of the handle space.  The modulo is
		// implicit.
		adjusted_high_next_handle0 =
			high_entry0->next_handle - hfact->handle_base;
		adjusted_low_next_handle0 =
			low_entry0->next_handle - hfact->handle_base;
		next_handle0 = __max(adjusted_high_next_handle0,
			adjusted_low_next_handle0) + hfact->handle_base - half_size;
		if (next_handle0 == 0)
		{
			// The handle value has wrapped around back to zero; however, zero
			// is a reserved value, so we instead set the next handle to the
			// subsequent legal value, which is the new table size.
			next_handle0 = half_size;
		}
		if (high_entry0->handle != high_entry0->next_handle)
		{
			// The high entry is assigned, so we copy its handle value and
			// reference pointer.  Also, we remove it from the assigned list
			// and replace it with the new entry.
			new_entry0->handle = high_entry0->handle;
			new_entry0->reference = high_entry0->reference;
			high_entry0->next_entry->prev_entry = new_entry0;
			high_entry0->prev_entry->next_entry = new_entry0;
			new_entry0->next_entry = high_entry0->next_entry;
			new_entry0->prev_entry = high_entry0->prev_entry;
		}
		else if (low_entry0->handle != low_entry0->next_handle)
		{
			// The low entry is assigned, so we copy its handle value and
			// reference pointer.  Also, we remove it from the assigned list
			// and replace it with the new entry.
			new_entry0->handle = low_entry0->handle;
			new_entry0->reference = low_entry0->reference;
			low_entry0->next_entry->prev_entry = new_entry0;
			low_entry0->prev_entry->next_entry = new_entry0;
			new_entry0->next_entry = low_entry0->next_entry;
			new_entry0->prev_entry = low_entry0->prev_entry;
		}
		else
		{
			// Neither entry is assigned, so we indicate an unassigned condition
			// in the new entry.
			new_entry0->handle = next_handle0;
			new_entry0->reference = 0;
			if (adjusted_high_next_handle0 < adjusted_low_next_handle0)
			{
				// The high entry next handle has a lesser value than the low
				// entry next handle, so the high entry must be on the primary
				// list.  We remove it from the primary list and replace it
				// with the new entry.
				high_entry0->next_entry->prev_entry = new_entry0;
				high_entry0->prev_entry->next_entry = new_entry0;
				new_entry0->next_entry = high_entry0->next_entry;
				new_entry0->prev_entry = high_entry0->prev_entry;
			}
			else
			{
				// The low entry next handle has a lesser value than the high
				// entry next handle, so the low entry must be on the primary
				// list.  We remove it from the primary list and replace it
				// with the new entry.
				low_entry0->next_entry->prev_entry = new_entry0;
				low_entry0->prev_entry->next_entry = new_entry0;
				new_entry0->next_entry = low_entry0->next_entry;
				new_entry0->prev_entry = low_entry0->prev_entry;
			}
		}
		// Set the next handle for the new entry.
		new_entry0->next_handle = next_handle0;
		// Now that we have merged high_entry1 and low_entry1 into new_entry1,
		// and independently merged high_entry0 and low_entry0 into new_entry0,
		// we examine the two new entries to determine on which list to place
		// each of them.  Note that we do not actually manipulate the lists in
		// this portion of the code; we merely make decisions and record these
		// decisions for the future.
		if (new_entry0->handle == new_entry0->next_handle &&
			new_entry1->handle == new_entry1->next_handle)
		{
			// Both new_entry0 and new_entry1 are unassigned, so one of them
			// belongs on the primary list and the other on the secondary list.
			// Which goes on which is determined by a comparison of their handle
			// values.  We're being tricky with unsigned integer math here.
			// Before comparing the two handles, we subtract from each the value
			// of handle_base, modulo the size of the handle space (the modulo
			// is implicit).  This allows the effective comparison of their
			// logical acyclic values rather than their actual cyclic values.
			adjusted_new_handle0 = new_entry0->handle - hfact->handle_base;
			adjusted_new_handle1 = new_entry1->handle - hfact->handle_base;
			if (adjusted_new_handle0 < adjusted_new_handle1)
			{
				// The handle value for new_entry0 is lower, so new_entry0
				// belongs on the primary list and new_entry1 on the secondary
				// list.  We indicate this decision in the list array.
				list[index] = LD_PRIMARY;
				list[quarter_size + index] = LD_SECONDARY;
			}
			else
			{
				// The handle value for new_entry1 is lower, so new_entry1
				// belongs on the primary list and new_entry0 on the secondary
				// list.  We indicate this decision in the list array.
				list[index] = LD_SECONDARY;
				list[quarter_size + index] = LD_PRIMARY;
			}
		}
		else
		{
			// Either new_entry0 or new_entry1 (or both) is assigned, and it is
			// therefore already on the assigned list.  If one of the entries
			// is not assigned, it belongs on the secondary list.  We indicate
			// this decision in both places of the list array, which is safe to
			// do since the assigned entry's list indicator will never be
			// examined.
			list[index] = LD_SECONDARY;
			list[quarter_size + index] = LD_SECONDARY;
		}
		if (new_entry0->handle != new_entry0->next_handle &&
			new_entry1->handle != new_entry1->next_handle)
		{
			// Both new_entry0 and new_entry1 are assigned, so they form a pair.
			// We thus increment the pair count.  Note that we never set the
			// pair count to zero above, but this was not necessary since the
			// table could not be contracted unless the pair count was zero.
			hfact->pair_count++;
		}
	}
	// At this point, the table has been completely contracted except for the
	// reassembly of the unassigned lists.  In the code above, any entries that
	// had previously been on the secondary list were merged with assigned
	// entries, so they are no longer relevant.  Only those entries that had
	// previously been (and are still) on the primary list will still be
	// unassigned.  We now loop through the primary list and place each list
	// element on the appropriate list, as indicated by the list array.  Doing
	// the list assignment in these two steps preserves the general order of
	// the entries, which has some value since they will tend to be partially
	// sorted.
	entry = hfact->entry_list[LD_PRIMARY].next_entry;
	primary_entry = &hfact->entry_list[LD_PRIMARY];
	secondary_entry = &hfact->entry_list[LD_SECONDARY];
	while (entry != &hfact->entry_list[LD_PRIMARY])
	{
		if (list[entry->handle & half_size - 1] == LD_PRIMARY)
		{
			// The list array indicates the primary list, so place the entry
			// onto the primary list.
			primary_entry->next_entry = entry;
			entry->prev_entry = primary_entry;
			primary_entry = entry;
		}
		else
		{
			// The list array indicates the secondary list, so place the entry
			// onto the secondary list.
			secondary_entry->next_entry = entry;
			entry->prev_entry = secondary_entry;
			secondary_entry = entry;
		}
		entry = entry->next_entry;
	}
	// Wrap up lists by connecting in tails.
	primary_entry->next_entry = &hfact->entry_list[LD_PRIMARY];
	hfact->entry_list[LD_PRIMARY].prev_entry = primary_entry;
	secondary_entry->next_entry = &hfact->entry_list[LD_SECONDARY];
	hfact->entry_list[LD_SECONDARY].prev_entry = secondary_entry;
	// This contraction increases the hysteresis debt by the cost of one set of
	// allocation and deallocation operations plus the cost of merging each
	// pair of entries into a single entry.
	hfact->hysteresis_debt += ALLOCATION_COST + half_size;
	// Save a pointer to the old entry table so that it can be deallocated.
	old_entries = hfact->entries;
	// Note that we have not modified the handle, next_handle, or reference
	// fields of any entries in the old table.  Therefore, any calls to the
	// dereference_HF_handle() routine that may have been made by other threads
	// during the above operations would have been performed successfully.
	// We are now about to decrease the table size and update the entries
	// variable to point to the new table.  These operations must be performed
	// atomically in order for the dereference routine to perform correctly.
	// We thus bracket the operations with increments to the verifier variables.
	// When the verifiers have the same value, the table_size and entries
	// variables are in a consistent state.  This is checked by the dereference
	// routine.
	hfact->verifier0++;                                // begin critical section
	hfact->table_size = half_size;
	hfact->entries = new_entries;
	hfact->verifier1 = hfact->verifier0;                 // end critical section
	
    // Deallocate the old table and the auxiliary list indicator array.
	GpcFreeMem(old_entries, handleFactoryTag);
	GpcFreeMem(list, handleFactoryTag);
	// return an indication of success.
	return 0;
}

// This function revokes handles that are between handle_base and handle_base
// + 2 * HANDLE_RANGE_STEP - 1, inclusive.  It then increments the value of
// handle_base by HANDLE_RANGE_STEP.  Suspended handles will be revoked one
// revokation pass later than non-suspended handles.
//
void revoke_ancient_HF_handles(
	HandleFactory *hfact)
{
	HFHandle new_handle_base;
	int half_size;
	int index;
	HFEntry *high_entry;
	HFEntry *low_entry;
	HFHandle adjusted_high_handle;
	HFHandle adjusted_low_handle;
	HFHandle adjusted_high_next_handle;
	HFHandle adjusted_low_next_handle;
	HFHandle handle;
	volatile HFEntry *seq_entry;                // volatile to ensure sequencing

	// Compute new handle base.
	new_handle_base = hfact->handle_base + HANDLE_RANGE_STEP;
	// It might seem reasonable to loop through each index of the table and
	// determine whether to revoke the handle of each entry.  This is in fact
	// what the following routine does; however, it does it by looping through
	// only half of the indices and examining two entries for each index.  It
	// does this so that it can compare the two entries to determine on which
	// list to place each of them.
	half_size = hfact->table_size / 2;
	for (index = 0; index < half_size; index++)
	{
		// We're looking at two entries at once.
		high_entry = &hfact->entries[half_size + index];
		low_entry = &hfact->entries[index];
		// We're being tricky with unsigned integer math here.  Before making
		// comparisons on either handle, we subtract from it the value of
		// handle_base, modulo the size of the handle space (the modulo is
		// implicit).  This allows the effective comparison of its logical
		// acyclic value rather than its actual cyclic value.
		adjusted_high_handle = high_entry->handle - hfact->handle_base;
		adjusted_low_handle = low_entry->handle - hfact->handle_base;
		if (adjusted_high_handle < 2 * HANDLE_RANGE_STEP ||
			adjusted_low_handle < 2 * HANDLE_RANGE_STEP)
		{
			// At least one of the handles is less than twice HANDLE_RANGE_STEP
			// more than the current handle base, so it will need to be updated.
			// For the vast majority of cases, this test is expected to fail,
			// and so all of the following work can be skipped.
			if (high_entry->handle != high_entry->next_handle &&
				low_entry->handle != low_entry->next_handle)
			{
				// Both of the entries are assigned, so, since at least one of
				// them will be revoked, we will be losing one pair.
				hfact->pair_count--;
			}
			if (high_entry->handle == high_entry->next_handle ||
				adjusted_high_handle < 2 * HANDLE_RANGE_STEP)
			{
				// Either the high entry is unassigned or in need of revokation
				// (after which it will be unassigned), so we remove it from
				// whatever list it is on.  We do this because all unassigned
				// entries will be added to the appropriate list below.
				high_entry->next_entry->prev_entry = high_entry->prev_entry;
				high_entry->prev_entry->next_entry = high_entry->next_entry;
				// Zeroing these pointers is unnecessary, but it will help to
				// catch any mistakes made further down.
				high_entry->next_entry = 0;
				high_entry->prev_entry = 0;
			}
			if (adjusted_high_handle < 2 * HANDLE_RANGE_STEP)
			{
				// The high handle needs to be updated.
				if (high_entry->handle != high_entry->next_handle)
				{
					// The high handle is assigned, so this updating will
					// revoke the handle.  Thus, we decrement the population.
					hfact->population--;
				}
				// Compute the handle value as the maximum of (1) the next
				// handle and (2) the new handle base plus the entry index.
				// We're being tricky with unsigned integer math here.  The
				// maximum involves partial decomposition of the sums, from
				// which we then subtract the value of handle_base, modulo the
				// size of the handle space (the modulo is implicit).  Thus,
				// the maximum is taken with respect to the logical acyclic
				// values rather than the actual cyclic values.
				adjusted_high_next_handle =
					high_entry->next_handle - hfact->handle_base;
				handle = __max(adjusted_high_next_handle,
					HANDLE_RANGE_STEP + half_size + index) + hfact->handle_base;
				// Since the high handle is -- by definition -- in the upper
				// half of the table, there is no need to check for the reserved
				// value of zero.
				// Update the handle value.  Since this updating will invalidate
				// the handle if it is currently assigned, the order of the
				// operations is important to correct multi-threaded operation.
				seq_entry = high_entry;
				seq_entry->next_handle = handle;
				seq_entry->handle = handle;           // first invalidate handle
				seq_entry->reference = 0;                // then clear reference
			}
			if (low_entry->handle == low_entry->next_handle ||
				adjusted_low_handle < 2 * HANDLE_RANGE_STEP)
			{
				// Either the low entry is unassigned or in need of revokation
				// (after which it will be unassigned), so we remove it from
				// whatever list it is on.  We do this because all unassigned
				// entries will be added to the appropriate list below.
				low_entry->next_entry->prev_entry = low_entry->prev_entry;
				low_entry->prev_entry->next_entry = low_entry->next_entry;
				// Zeroing these pointers is unnecessary, but it will help to
				// catch any mistakes made further down.
				low_entry->next_entry = 0;
				low_entry->prev_entry = 0;
			}
			if (adjusted_low_handle < 2 * HANDLE_RANGE_STEP)
			{
				// The low handle needs to be updated.
				if (low_entry->handle != low_entry->next_handle)
				{
					// The low handle is assigned, so this updating will
					// revoke the handle.  Thus, we decrement the population.
					hfact->population--;
				}
				// Compute the handle value as the maximum of (1) the next
				// handle and (2) the new handle base plus the entry index.
				// We're being tricky with unsigned integer math here.  The
				// maximum involves partial decomposition of the sums, from
				// which we then subtract the value of handle_base, modulo the
				// size of the handle space (the modulo is implicit).  Thus,
				// the maximum is taken with respect to the logical acyclic
				// values rather than the actual cyclic values.
				adjusted_low_next_handle =
					low_entry->next_handle - hfact->handle_base;
				handle = __max(adjusted_low_next_handle,
					HANDLE_RANGE_STEP + index) + hfact->handle_base;
				if (handle == 0)
				{
					// The handle value has wrapped around back to zero;
					// however, zero is a reserved value, so we instead set the
					// handle to the subsequent legal value, which is the table
					// size.
					handle = hfact->table_size;
				}
				// Update the handle value.  Since this updating will invalidate
				// the handle if it is currently assigned, the order of the
				// operations is important to correct multi-threaded operation.
				seq_entry = low_entry;
				seq_entry->next_handle = handle;
				seq_entry->handle = handle;           // first invalidate handle
				seq_entry->reference = 0;                // then clear reference
			}
			if (high_entry->handle != high_entry->next_handle)
			{
				// The high entry is still assigned, so the low entry belongs
				// on the secondary list.
				low_entry->next_entry = &hfact->entry_list[LD_SECONDARY];
				low_entry->prev_entry =
					hfact->entry_list[LD_SECONDARY].prev_entry;
				hfact->entry_list[LD_SECONDARY].prev_entry->next_entry =
					low_entry;
				hfact->entry_list[LD_SECONDARY].prev_entry = low_entry;
			}
			else if (low_entry->handle != low_entry->next_handle)
			{
				// The low entry is still assigned, so the high entry belongs
				// on the secondary list.
				high_entry->next_entry = &hfact->entry_list[LD_SECONDARY];
				high_entry->prev_entry =
					hfact->entry_list[LD_SECONDARY].prev_entry;
				hfact->entry_list[LD_SECONDARY].prev_entry->next_entry =
					high_entry;
				hfact->entry_list[LD_SECONDARY].prev_entry = high_entry;
			}
			else
			{
				// Neither entry is still assigned, so one entry belongs on the
				// primary list and one on the secondary list.  Which goes on
				// which is determined by a comparison of their handle values.
				// We're being tricky with unsigned integer math here.  Before
				// comparing the two handles, we subtract from each the value
				// of handle_base, modulo the size of the handle space (the
				// modulo is implicit).  This allows the effective comparison
				// of their logical acyclic values rather than their actual
				// cyclic values.
				adjusted_high_next_handle =
					high_entry->next_handle - new_handle_base;
				adjusted_low_next_handle =
					low_entry->next_handle - new_handle_base;
				if (adjusted_low_next_handle < adjusted_high_next_handle)
				{
					// The handle value for the low entry is smaller, so it
					// belongs on the primary list and the high entry on the
					// secondary list.
					high_entry->next_entry = &hfact->entry_list[LD_SECONDARY];
					high_entry->prev_entry =
						hfact->entry_list[LD_SECONDARY].prev_entry;
					hfact->entry_list[LD_SECONDARY].prev_entry->next_entry =
						high_entry;
					hfact->entry_list[LD_SECONDARY].prev_entry = high_entry;
					low_entry->next_entry = &hfact->entry_list[LD_PRIMARY];
					low_entry->prev_entry =
						hfact->entry_list[LD_PRIMARY].prev_entry;
					hfact->entry_list[LD_PRIMARY].prev_entry->next_entry =
						low_entry;
					hfact->entry_list[LD_PRIMARY].prev_entry = low_entry;
				}
				else
				{
					// The handle value for the high entry is smaller, so it
					// belongs on the primary list and the low entry on the
					// secondary list.
					high_entry->next_entry = &hfact->entry_list[LD_PRIMARY];
					high_entry->prev_entry =
						hfact->entry_list[LD_PRIMARY].prev_entry;
					hfact->entry_list[LD_PRIMARY].prev_entry->next_entry =
						high_entry;
					hfact->entry_list[LD_PRIMARY].prev_entry = high_entry;
					low_entry->next_entry = &hfact->entry_list[LD_SECONDARY];
					low_entry->prev_entry =
						hfact->entry_list[LD_SECONDARY].prev_entry;
					hfact->entry_list[LD_SECONDARY].prev_entry->next_entry =
						low_entry;
					hfact->entry_list[LD_SECONDARY].prev_entry = low_entry;
				}
			}
		}
	}
	// Update the handle base with the new handle base.
	hfact->handle_base = new_handle_base;
	// To contract the table, there must be no pairs, because otherwise two
	// assigned handles would yield the same entry index and thereby conflict.
	// Furthermore, the table size must be greater than 2, because much of the
	// handle factory code assumes that the table is at least of size 2.  In
	// addition to these strict requirements, hysteresis is employed both to
	// keep the mean assignment and release times constant and to minimize the
	// allocation chatter of rapidly expanding and contracting the table.  Only
	// if the hysteresis debt is zero will the table be contracted.
	if (hfact->pair_count == 0 && hfact->table_size > 2 &&
		hfact->hysteresis_debt == 0)
	{
		contract_HF_table(hfact);
		// Note that we ignore the return code.  If the contraction is
		// unsuccessful, we just continue as usual.  There is no real harm in
		// not contracting the table, except that we consume more space than
		// necessary.
	}
}