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_TYPE *	PPH_OBJECT_TYPE

typedef struct _PH_QUEUED_LOCK	PH_QUEUED_LOCK

typedef struct _PH_QUEUED_LOCK *	PPH_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_POOL *	PPH_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.

typedef struct _PH_OBJECT_TYPE_INFORMATION PH_OBJECT_TYPE_INFORMATION

typedef struct _PH_OBJECT_TYPE_PARAMETERS PH_OBJECT_TYPE_PARAMETERS

typedef struct _PH_QUEUED_LOCK PH_QUEUED_LOCK

Definition at line 57 of file ref.h.

typedef struct _PH_AUTO_POOL * PPH_AUTO_POOL

typedef struct _PH_OBJECT_TYPE* PPH_OBJECT_TYPE

Definition at line 54 of file ref.h.

typedef struct _PH_OBJECT_TYPE_INFORMATION * PPH_OBJECT_TYPE_INFORMATION

typedef struct _PH_OBJECT_TYPE_PARAMETERS * PPH_OBJECT_TYPE_PARAMETERS

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

Object	A pointer to the object being freed.
Flags	Reserved.

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

Object A 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

Size	The 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

ObjectSize	The size of the object.
ObjectType	The 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

Name	The name of the type.
Flags	A combination of flags affecting the behaviour of the object type.
DeleteProcedure	A 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

Name	The name of the type.
Flags	A combination of flags affecting the behaviour of the object type.
DeleteProcedure	A callback function that is executed when an object of this type is about to be freed (i.e. when its reference count is 0).
Parameters	A 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

AutoPool The 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

Object A 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

Object A 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

Object	A pointer to the object to dereference.
RefCount	The number of references to remove.
DeferDelete	Whether 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

AutoPool The 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

Object A 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

ObjectType	A pointer to an object type.
Information	A 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

Object A 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

Object	A pointer to the object to reference.
RefCount	The 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

Object The 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.

Data Structures

Macros

Typedefs

Functions

Variables

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation