429 lines
8.9 KiB
C
429 lines
8.9 KiB
C
/*++
|
||
|
||
Copyright (c) 1998, Microsoft Corporation
|
||
|
||
Module Name:
|
||
|
||
compref.h
|
||
|
||
Abstract:
|
||
|
||
This module contains declarations for maintaining reference-count
|
||
on a component. It provides an asynchronous thread-safe means of
|
||
handling cleanup in a module.
|
||
|
||
The mechanism defined uses a locked reference count and cleanup-routine
|
||
to manage the lifetime of the component. When the reference-count
|
||
is dropped to zero, the associated cleanup-routine is invoked.
|
||
|
||
Author:
|
||
|
||
Abolade Gbadegesin (aboladeg) 6-Mar-1998
|
||
|
||
Revision History:
|
||
|
||
--*/
|
||
|
||
#ifndef _NATHLP_COMPREF_H_
|
||
#define _NATHLP_COMPREF_H_
|
||
|
||
|
||
#if 0
|
||
typedef
|
||
VOID
|
||
(*PCOMPONENT_CLEANUP_ROUTINE)(
|
||
VOID
|
||
);
|
||
|
||
//
|
||
// Structure: COMPONENT_REFERENCE
|
||
//
|
||
// This structure must reside in memory for the lifetime of the component
|
||
// to which it refers. It is used to synchronize the component's execution.
|
||
//
|
||
|
||
typedef struct _COMPONENT_REFERENCE {
|
||
CRITICAL_SECTION Lock;
|
||
ULONG ReferenceCount;
|
||
BOOLEAN Deleted;
|
||
PCOMPONENT_CLEANUP_ROUTINE CleanupRoutine;
|
||
#if COMPREF_TRACKING
|
||
struct _COMPREF_RECORD* RecordArray;
|
||
ULONG RecordIndex;
|
||
#endif
|
||
} COMPONENT_REFERENCE, *PCOMPONENT_REFERENCE;
|
||
|
||
#if COMPREF_TRACKING
|
||
#define COMPREF_RECORD_COUNT (1024)
|
||
typedef struct _COMPREF_RECORD {
|
||
PCHAR File;
|
||
USHORT Line;
|
||
UCHAR ReferenceCount;
|
||
enum {
|
||
ComprefAcquireRecord,
|
||
ComprefReleaseRecord
|
||
} Type;
|
||
} COMPREF_RECORD, *PCOMPREF_RECORD;
|
||
#endif
|
||
|
||
|
||
//
|
||
// FUNCTION DECLARATIONS
|
||
//
|
||
|
||
__inline
|
||
BOOLEAN
|
||
AcquireComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
);
|
||
|
||
VOID
|
||
__inline
|
||
DeleteComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
);
|
||
|
||
ULONG
|
||
__inline
|
||
InitializeComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference,
|
||
PCOMPONENT_CLEANUP_ROUTINE CleanupRoutine
|
||
);
|
||
|
||
#if COMPREF_TRACKING
|
||
__inline
|
||
BOOLEAN
|
||
RecordComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference,
|
||
PCHAR File,
|
||
ULONG Line,
|
||
UCHAR Type
|
||
);
|
||
#endif
|
||
|
||
__inline
|
||
BOOLEAN
|
||
ReleaseComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
);
|
||
|
||
__inline
|
||
BOOLEAN
|
||
ReleaseInitialComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
);
|
||
|
||
__inline
|
||
VOID
|
||
ResetComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
);
|
||
|
||
//
|
||
// MACRO DECLARATIONS
|
||
//
|
||
|
||
#define RETURN_VOID
|
||
|
||
#if COMPREF_TRACKING
|
||
|
||
#define REFERENCE_COMPONENT(c) \
|
||
RecordComponentReference(c, __FILE__, __LINE__, ComprefAcquireRecord)
|
||
|
||
#define DEREFERENCE_COMPONENT(c) \
|
||
RecordComponentReference(c, __FILE__, __LINE__, ComprefReleaseRecord)
|
||
|
||
#define REFERENCE_COMPONENT_OR_RETURN(c,retcode) \
|
||
if (!RecordComponentReference(c, __FILE__, __LINE__, ComprefAcquireRecord)) { return retcode; }
|
||
|
||
#define DEREFERENCE_COMPONENT_AND_RETURN(c,retcode) \
|
||
RecordComponentReference(c, __FILE__, __LINE__, ComprefReleaseRecord); \
|
||
return retcode
|
||
|
||
#else
|
||
|
||
#define REFERENCE_COMPONENT(c) \
|
||
AcquireComponentReference(c)
|
||
|
||
#define DEREFERENCE_COMPONENT(c) \
|
||
ReleaseComponentReference(c)
|
||
|
||
#define REFERENCE_COMPONENT_OR_RETURN(c,retcode) \
|
||
if (!AcquireComponentReference(c)) { return retcode; }
|
||
|
||
#define DEREFERENCE_COMPONENT_AND_RETURN(c,retcode) \
|
||
ReleaseComponentReference(c); return retcode
|
||
|
||
#endif
|
||
|
||
|
||
//
|
||
// INLINE ROUTINE IMPLEMENTATIONS
|
||
//
|
||
|
||
__inline
|
||
BOOLEAN
|
||
AcquireComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
)
|
||
|
||
/*++
|
||
|
||
Routine Description:
|
||
|
||
This routine is called to increment the reference-count to a component.
|
||
The attempt may fail if the initial reference has been released
|
||
and the component is therefore being deleted.
|
||
|
||
Arguments:
|
||
|
||
ComponentReference - the component to be referenced
|
||
|
||
Return Value:
|
||
|
||
BOOLEAN - TRUE if the component was referenced, FALSE otherwise.
|
||
|
||
--*/
|
||
|
||
{
|
||
EnterCriticalSection(&ComponentReference->Lock);
|
||
if (ComponentReference->Deleted) {
|
||
LeaveCriticalSection(&ComponentReference->Lock);
|
||
return FALSE;
|
||
}
|
||
++ComponentReference->ReferenceCount;
|
||
LeaveCriticalSection(&ComponentReference->Lock);
|
||
return TRUE;
|
||
|
||
} // AcquireComponentReference
|
||
|
||
|
||
VOID
|
||
__inline
|
||
DeleteComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
)
|
||
|
||
/*++
|
||
|
||
Routine Description:
|
||
|
||
This routine is called to destroy a component reference.
|
||
It may only be called after the last reference to the component is released,
|
||
i.e. after 'ReleaseComponentReference' has returned 'TRUE'.
|
||
It may also be called from within the component's 'CleanupRoutine'.
|
||
|
||
Arguments:
|
||
|
||
ComponentReference - the component to be destroyed
|
||
|
||
Return Value:
|
||
|
||
none.
|
||
|
||
--*/
|
||
|
||
{
|
||
DeleteCriticalSection(&ComponentReference->Lock);
|
||
#if COMPREF_TRACKING
|
||
HeapFree(GetProcessHeap(), 0, ComponentReference->RecordArray);
|
||
#endif
|
||
|
||
} // DeleteComponentReference
|
||
|
||
|
||
ULONG
|
||
__inline
|
||
InitializeComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference,
|
||
PCOMPONENT_CLEANUP_ROUTINE CleanupRoutine
|
||
)
|
||
|
||
/*++
|
||
|
||
Routine Description:
|
||
|
||
This routine is called to initialize a component reference.
|
||
|
||
Arguments:
|
||
|
||
ComponentReference - the component to be initialized
|
||
|
||
CleanupRoutine - the routine to be called when the component
|
||
is to be cleaned up (within the final 'ReleaseComponentReference').
|
||
|
||
Return Value:
|
||
|
||
none.
|
||
|
||
--*/
|
||
|
||
{
|
||
__try {
|
||
InitializeCriticalSection(&ComponentReference->Lock);
|
||
}
|
||
__except (EXCEPTION_EXECUTE_HANDLER) {
|
||
return GetExceptionCode();
|
||
}
|
||
ComponentReference->Deleted = FALSE;
|
||
ComponentReference->ReferenceCount = 1;
|
||
ComponentReference->CleanupRoutine = CleanupRoutine;
|
||
#if COMPREF_TRACKING
|
||
ComponentReference->RecordIndex = 0;
|
||
ComponentReference->RecordArray =
|
||
HeapAlloc(
|
||
GetProcessHeap(), 0, sizeof(COMPREF_RECORD) * COMPREF_RECORD_COUNT
|
||
);
|
||
#endif
|
||
return NO_ERROR;
|
||
|
||
} // InitializeComponentReference
|
||
|
||
|
||
|
||
#if COMPREF_TRACKING
|
||
__inline
|
||
BOOLEAN
|
||
RecordComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference,
|
||
PCHAR File,
|
||
ULONG Line,
|
||
UCHAR Type
|
||
)
|
||
{
|
||
BOOLEAN Success;
|
||
ULONG i = InterlockedIncrement(&ComponentReference->RecordIndex);
|
||
i %= COMPREF_RECORD_COUNT;
|
||
ComponentReference->RecordArray[i].File = File;
|
||
ComponentReference->RecordArray[i].Line = (USHORT)Line;
|
||
ComponentReference->RecordArray[i].Type = Type;
|
||
if (Type == ComprefAcquireRecord) {
|
||
Success = AcquireComponentReference(ComponentReference);
|
||
} else {
|
||
Success = ReleaseComponentReference(ComponentReference);
|
||
}
|
||
ComponentReference->RecordArray[i].ReferenceCount =
|
||
(UCHAR)ComponentReference->ReferenceCount;
|
||
return Success;
|
||
}
|
||
|
||
#endif
|
||
|
||
__inline
|
||
BOOLEAN
|
||
ReleaseComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
)
|
||
|
||
/*++
|
||
|
||
Routine Description:
|
||
|
||
This routine is called to drop a reference to a component.
|
||
If the reference drops to zero, cleanup is performed.
|
||
Otherwise, cleanup occurs later when the last reference is released.
|
||
|
||
Arguments:
|
||
|
||
ComponentReference - the component to be referenced
|
||
|
||
Return Value:
|
||
|
||
BOOLEAN - TRUE if the component was cleaned up, FALSE otherwise.
|
||
|
||
--*/
|
||
|
||
{
|
||
EnterCriticalSection(&ComponentReference->Lock);
|
||
if (--ComponentReference->ReferenceCount) {
|
||
LeaveCriticalSection(&ComponentReference->Lock);
|
||
return FALSE;
|
||
}
|
||
LeaveCriticalSection(&ComponentReference->Lock);
|
||
ComponentReference->CleanupRoutine();
|
||
return TRUE;
|
||
} // ReleaseComponentReference
|
||
|
||
|
||
__inline
|
||
BOOLEAN
|
||
ReleaseInitialComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
)
|
||
|
||
/*++
|
||
|
||
Routine Description:
|
||
|
||
This routine is called to drop the initial reference to a component,
|
||
and mark the component as deleted.
|
||
If the reference drops to zero, cleanup is performed right away.
|
||
|
||
Arguments:
|
||
|
||
ComponentReference - the component to be referenced
|
||
|
||
Return Value:
|
||
|
||
BOOLEAN - TRUE if the component was cleaned up, FALSE otherwise.
|
||
|
||
--*/
|
||
|
||
{
|
||
EnterCriticalSection(&ComponentReference->Lock);
|
||
if (ComponentReference->Deleted) {
|
||
LeaveCriticalSection(&ComponentReference->Lock);
|
||
return TRUE;
|
||
}
|
||
ComponentReference->Deleted = TRUE;
|
||
if (--ComponentReference->ReferenceCount) {
|
||
LeaveCriticalSection(&ComponentReference->Lock);
|
||
return FALSE;
|
||
}
|
||
LeaveCriticalSection(&ComponentReference->Lock);
|
||
ComponentReference->CleanupRoutine();
|
||
return TRUE;
|
||
} // ReleaseInitialComponentReference
|
||
|
||
|
||
__inline
|
||
VOID
|
||
ResetComponentReference(
|
||
PCOMPONENT_REFERENCE ComponentReference
|
||
)
|
||
|
||
/*++
|
||
|
||
Routine Description:
|
||
|
||
This routine is called to reset a component reference
|
||
to an initial state.
|
||
|
||
Arguments:
|
||
|
||
ComponentReference - the component to be reset
|
||
|
||
Return Value:
|
||
|
||
none.
|
||
|
||
--*/
|
||
|
||
{
|
||
EnterCriticalSection(&ComponentReference->Lock);
|
||
ComponentReference->ReferenceCount = 1;
|
||
ComponentReference->Deleted = FALSE;
|
||
#if COMPREF_TRACKING
|
||
ComponentReference->RecordIndex = 0;
|
||
ZeroMemory(
|
||
ComponentReference->RecordArray,
|
||
sizeof(COMPREF_RECORD) * COMPREF_RECORD_COUNT
|
||
);
|
||
#endif
|
||
LeaveCriticalSection(&ComponentReference->Lock);
|
||
} // ReleaseComponentReference
|
||
|
||
#endif
|
||
|
||
#endif // _NATHLP_COMPREF_H_
|