Process Hacker
ref.h File Reference

Go to the source code of this file.

Data Structures

struct  _PH_OBJECT_TYPE_PARAMETERS
 
struct  _PH_OBJECT_TYPE_INFORMATION
 
struct  _PH_AUTO_POOL
 An auto-dereference pool can be used for semi-automatic reference counting. More...
 

Macros

#define PH_OBJECT_SMALL_OBJECT_SIZE   48
 
#define PH_OBJECT_SMALL_OBJECT_COUNT   512
 
#define PH_OBJECT_TYPE_USE_FREE_LIST   0x00000001
 
#define PH_OBJECT_TYPE_VALID_FLAGS   0x00000001
 
#define PH_AUTO_POOL_STATIC_SIZE   64
 The size of the static array in an auto-release pool.
 
#define PH_AUTO_POOL_DYNAMIC_BIG_SIZE   256
 The maximum size of the dynamic array for it to be kept after the auto-release pool is drained.
 

Typedefs

typedef VOID(NTAPI * PPH_TYPE_DELETE_PROCEDURE )(_In_ PVOID Object, _In_ ULONG Flags)
 The delete procedure for an object type, called when an object of the type is being freed.
 
typedef struct _PH_OBJECT_TYPEPPH_OBJECT_TYPE
 
typedef struct _PH_QUEUED_LOCK PH_QUEUED_LOCK
 
typedef struct _PH_QUEUED_LOCKPPH_QUEUED_LOCK
 
typedef struct
_PH_OBJECT_TYPE_PARAMETERS 
PH_OBJECT_TYPE_PARAMETERS
 
typedef struct
_PH_OBJECT_TYPE_PARAMETERS
PPH_OBJECT_TYPE_PARAMETERS
 
typedef struct
_PH_OBJECT_TYPE_INFORMATION 
PH_OBJECT_TYPE_INFORMATION
 
typedef struct
_PH_OBJECT_TYPE_INFORMATION
PPH_OBJECT_TYPE_INFORMATION
 
typedef struct _PH_AUTO_POOL PH_AUTO_POOL
 An auto-dereference pool can be used for semi-automatic reference counting.
 
typedef struct _PH_AUTO_POOLPPH_AUTO_POOL
 

Functions

NTSTATUS PhInitializeRef (VOID)
 Initializes the object manager module.
 
_May_raise_ PHLIBAPI PVOID NTAPI PhCreateObject (_In_ SIZE_T ObjectSize, _In_ PPH_OBJECT_TYPE ObjectType)
 Allocates a object.
 
PHLIBAPI PVOID NTAPI PhReferenceObject (_In_ PVOID Object)
 References the specified object.
 
_May_raise_ PHLIBAPI LONG NTAPI PhReferenceObjectEx (_In_ PVOID Object, _In_ LONG RefCount)
 References the specified object.
 
PHLIBAPI BOOLEAN NTAPI PhReferenceObjectSafe (_In_ PVOID Object)
 Attempts to reference an object and fails if it is being destroyed.
 
PHLIBAPI VOID NTAPI PhDereferenceObject (_In_ PVOID Object)
 Dereferences the specified object.
 
PHLIBAPI BOOLEAN NTAPI PhDereferenceObjectDeferDelete (_In_ PVOID Object)
 Dereferences the specified object.
 
_May_raise_ PHLIBAPI LONG NTAPI PhDereferenceObjectEx (_In_ PVOID Object, _In_ LONG RefCount, _In_ BOOLEAN DeferDelete)
 Dereferences the specified object.
 
PHLIBAPI PPH_OBJECT_TYPE NTAPI PhGetObjectType (_In_ PVOID Object)
 Gets an object's type.
 
PHLIBAPI PPH_OBJECT_TYPE NTAPI PhCreateObjectType (_In_ PWSTR Name, _In_ ULONG Flags, _In_opt_ PPH_TYPE_DELETE_PROCEDURE DeleteProcedure)
 Creates an object type.
 
PHLIBAPI PPH_OBJECT_TYPE NTAPI PhCreateObjectTypeEx (_In_ PWSTR Name, _In_ ULONG Flags, _In_opt_ PPH_TYPE_DELETE_PROCEDURE DeleteProcedure, _In_opt_ PPH_OBJECT_TYPE_PARAMETERS Parameters)
 Creates an object type.
 
PHLIBAPI VOID NTAPI PhGetObjectTypeInformation (_In_ PPH_OBJECT_TYPE ObjectType, _Out_ PPH_OBJECT_TYPE_INFORMATION Information)
 Gets information about an object type.
 
PHLIBAPI PVOID NTAPI PhCreateAlloc (_In_ SIZE_T Size)
 Creates a reference-counted memory block.
 
FORCEINLINE VOID PhSwapReference (_Inout_ PVOID *ObjectReference, _In_opt_ PVOID NewObject)
 
FORCEINLINE VOID PhMoveReference (_Inout_ PVOID *ObjectReference, _In_opt_ _Assume_refs_(1) PVOID NewObject)
 
FORCEINLINE VOID PhSetReference (_Out_ PVOID *ObjectReference, _In_opt_ PVOID NewObject)
 
FORCEINLINE VOID PhClearReference (_Inout_ PVOID *ObjectReference)
 
PHLIBAPI VOID NTAPI PhInitializeAutoPool (_Out_ PPH_AUTO_POOL AutoPool)
 Initializes an auto-dereference pool and sets it as the current pool for the current thread.
 
_May_raise_ PHLIBAPI VOID NTAPI PhDeleteAutoPool (_Inout_ PPH_AUTO_POOL AutoPool)
 Deletes an auto-dereference pool.
 
PHLIBAPI VOID NTAPI PhDrainAutoPool (_In_ PPH_AUTO_POOL AutoPool)
 Dereferences and removes all objects in an auto-release pool.
 
_May_raise_ PHLIBAPI PVOID NTAPI PhAutoDereferenceObject (_In_opt_ PVOID Object)
 Adds an object to the current auto-dereference pool for the current thread.
 
PHLIBAPI VOID NTAPI PhaDereferenceObject (PVOID Object)
 Deprecated.
 

Variables

PPH_OBJECT_TYPE PhObjectTypeObject
 
PPH_OBJECT_TYPE PhAllocType
 

Macro Definition Documentation

#define PH_AUTO_POOL_DYNAMIC_BIG_SIZE   256

The maximum size of the dynamic array for it to be kept after the auto-release pool is drained.

Definition at line 255 of file ref.h.

#define PH_AUTO_POOL_STATIC_SIZE   64

The size of the static array in an auto-release pool.

Definition at line 252 of file ref.h.

#define PH_OBJECT_SMALL_OBJECT_COUNT   512

Definition at line 33 of file ref.h.

#define PH_OBJECT_SMALL_OBJECT_SIZE   48

Definition at line 32 of file ref.h.

#define PH_OBJECT_TYPE_USE_FREE_LIST   0x00000001

Definition at line 36 of file ref.h.

#define PH_OBJECT_TYPE_VALID_FLAGS   0x00000001

Definition at line 37 of file ref.h.

Typedef Documentation

typedef struct _PH_AUTO_POOL PH_AUTO_POOL

An auto-dereference pool can be used for semi-automatic reference counting.

Batches of objects are dereferenced at a certain time.

This object is not thread-safe and cannot be used across thread boundaries. Always store them as local variables.

Definition at line 57 of file ref.h.

typedef struct _PH_AUTO_POOL * PPH_AUTO_POOL

Definition at line 54 of file ref.h.

typedef struct _PH_QUEUED_LOCK * PPH_QUEUED_LOCK

Definition at line 57 of file ref.h.

typedef VOID(NTAPI * PPH_TYPE_DELETE_PROCEDURE)(_In_ PVOID Object, _In_ ULONG Flags)

The delete procedure for an object type, called when an object of the type is being freed.

Parameters
ObjectA pointer to the object being freed.
FlagsReserved.

Definition at line 48 of file ref.h.

Function Documentation

PHLIBAPI VOID NTAPI PhaDereferenceObject ( PVOID  Object)

Deprecated.

Use PhAutoDereferenceObject instead.

Definition at line 768 of file ref.c.

_May_raise_ PHLIBAPI PVOID NTAPI PhAutoDereferenceObject ( _In_opt_ PVOID  Object)

Adds an object to the current auto-dereference pool for the current thread.

If the current thread does not have an auto-dereference pool, the function raises an exception.

Parameters
ObjectA pointer to an object. The object will be dereferenced when the current auto-dereference pool is drained or freed.

Definition at line 717 of file ref.c.

FORCEINLINE VOID PhClearReference ( _Inout_ PVOID *  ObjectReference)

Definition at line 242 of file ref.h.

PHLIBAPI PVOID NTAPI PhCreateAlloc ( _In_ SIZE_T  Size)

Creates a reference-counted memory block.

Parameters
SizeThe number of bytes to allocate.
Returns
A pointer to the memory block.

Definition at line 583 of file ref.c.

_May_raise_ PHLIBAPI PVOID NTAPI PhCreateObject ( _In_ SIZE_T  ObjectSize,
_In_ PPH_OBJECT_TYPE  ObjectType 
)

Allocates a object.

Parameters
ObjectSizeThe size of the object.
ObjectTypeThe type of the object.
Returns
A pointer to the newly allocated object.

Definition at line 97 of file ref.c.

PHLIBAPI PPH_OBJECT_TYPE NTAPI PhCreateObjectType ( _In_ PWSTR  Name,
_In_ ULONG  Flags,
_In_opt_ PPH_TYPE_DELETE_PROCEDURE  DeleteProcedure 
)

Creates an object type.

Parameters
NameThe name of the type.
FlagsA combination of flags affecting the behaviour of the object type.
DeleteProcedureA callback function that is executed when an object of this type is about to be freed (i.e. when its reference count is 0).
Returns
A pointer to the newly created object type.
Remarks
Do not reference or dereference the object type once it is created.

Definition at line 350 of file ref.c.

PHLIBAPI PPH_OBJECT_TYPE NTAPI PhCreateObjectTypeEx ( _In_ PWSTR  Name,
_In_ ULONG  Flags,
_In_opt_ PPH_TYPE_DELETE_PROCEDURE  DeleteProcedure,
_In_opt_ PPH_OBJECT_TYPE_PARAMETERS  Parameters 
)

Creates an object type.

Parameters
NameThe name of the type.
FlagsA combination of flags affecting the behaviour of the object type.
DeleteProcedureA callback function that is executed when an object of this type is about to be freed (i.e. when its reference count is 0).
ParametersA structure containing additional parameters for the object type.
Returns
A pointer to the newly created object type.
Remarks
Do not reference or dereference the object type once it is created.

Definition at line 381 of file ref.c.

_May_raise_ PHLIBAPI VOID NTAPI PhDeleteAutoPool ( _Inout_ PPH_AUTO_POOL  AutoPool)

Deletes an auto-dereference pool.

The function will dereference any objects currently in the pool. If a pool other than the current pool is passed to the function, an exception is raised.

Parameters
AutoPoolThe auto-dereference pool to delete.

Definition at line 656 of file ref.c.

PHLIBAPI VOID NTAPI PhDereferenceObject ( _In_ PVOID  Object)

Dereferences the specified object.

The object will be freed if its reference count reaches 0.

Parameters
ObjectA pointer to the object to dereference.
Returns
TRUE if the object was freed, otherwise FALSE.

Definition at line 237 of file ref.c.

PHLIBAPI BOOLEAN NTAPI PhDereferenceObjectDeferDelete ( _In_ PVOID  Object)

Dereferences the specified object.

The object will be freed in a worker thread if its reference count reaches 0.

Parameters
ObjectA pointer to the object to dereference.
Returns
TRUE if the object was freed, otherwise FALSE.

Definition at line 265 of file ref.c.

_May_raise_ PHLIBAPI LONG NTAPI PhDereferenceObjectEx ( _In_ PVOID  Object,
_In_ LONG  RefCount,
_In_ BOOLEAN  DeferDelete 
)

Dereferences the specified object.

The object will be freed if its reference count reaches 0.

Parameters
ObjectA pointer to the object to dereference.
RefCountThe number of references to remove.
DeferDeleteWhether to defer deletion of the object.
Returns
The new reference count of the object.

Definition at line 282 of file ref.c.

PHLIBAPI VOID NTAPI PhDrainAutoPool ( _In_ PPH_AUTO_POOL  AutoPool)

Dereferences and removes all objects in an auto-release pool.

Parameters
AutoPoolThe auto-release pool to drain.

Definition at line 680 of file ref.c.

PHLIBAPI PPH_OBJECT_TYPE NTAPI PhGetObjectType ( _In_ PVOID  Object)

Gets an object's type.

Parameters
ObjectA pointer to an object.
Returns
A pointer to a type object.

Definition at line 328 of file ref.c.

PHLIBAPI VOID NTAPI PhGetObjectTypeInformation ( _In_ PPH_OBJECT_TYPE  ObjectType,
_Out_ PPH_OBJECT_TYPE_INFORMATION  Information 
)

Gets information about an object type.

Parameters
ObjectTypeA pointer to an object type.
InformationA variable which receives information about the object type.

Definition at line 433 of file ref.c.

PHLIBAPI VOID NTAPI PhInitializeAutoPool ( _Out_ PPH_AUTO_POOL  AutoPool)

Initializes an auto-dereference pool and sets it as the current pool for the current thread.

You must call PhDeleteAutoPool() before storage for the auto-dereference pool is freed.

Remarks
Always store auto-dereference pools in local variables, and do not share the pool with any other functions.

Definition at line 632 of file ref.c.

NTSTATUS PhInitializeRef ( VOID  )

Initializes the object manager module.

Definition at line 49 of file ref.c.

FORCEINLINE VOID PhMoveReference ( _Inout_ PVOID *  ObjectReference,
_In_opt_ _Assume_refs_(1) PVOID  NewObject 
)

Definition at line 215 of file ref.h.

PHLIBAPI PVOID NTAPI PhReferenceObject ( _In_ PVOID  Object)

References the specified object.

Parameters
ObjectA pointer to the object to reference.
Returns
The object.

Definition at line 161 of file ref.c.

_May_raise_ PHLIBAPI LONG NTAPI PhReferenceObjectEx ( _In_ PVOID  Object,
_In_ LONG  RefCount 
)

References the specified object.

Parameters
ObjectA pointer to the object to reference.
RefCountThe number of references to add.
Returns
The new reference count of the object.

Definition at line 182 of file ref.c.

PHLIBAPI BOOLEAN NTAPI PhReferenceObjectSafe ( _In_ PVOID  Object)

Attempts to reference an object and fails if it is being destroyed.

Parameters
ObjectThe object to reference if it is not being deleted.
Returns
TRUE if the object was referenced, FALSE if it was being deleted and was not referenced.
Remarks
This function is useful if a reference to an object is held, protected by a mutex, and the delete procedure of the object's type attempts to acquire the mutex. If this function is called while the mutex is owned, you can avoid referencing an object that is being destroyed.

Definition at line 215 of file ref.c.

FORCEINLINE VOID PhSetReference ( _Out_ PVOID *  ObjectReference,
_In_opt_ PVOID  NewObject 
)

Definition at line 230 of file ref.h.

FORCEINLINE VOID PhSwapReference ( _Inout_ PVOID *  ObjectReference,
_In_opt_ PVOID  NewObject 
)

Definition at line 199 of file ref.h.

Variable Documentation

PPH_OBJECT_TYPE PhAllocType

Definition at line 31 of file ref.c.

PPH_OBJECT_TYPE PhObjectTypeObject

Definition at line 28 of file ref.c.