#include <phbase.h>
#include <phintrnl.h>
#include <refp.h>

Macros
#define	_PH_REF_PRIVATE

#define	REF_STAT_UP(Name) PHLIB_INC_STATISTIC(Name)

Functions
NTSTATUS	PhInitializeRef (VOID)
	Initializes the object manager module.

_May_raise_ PVOID	PhCreateObject (_In_ SIZE_T ObjectSize, _In_ PPH_OBJECT_TYPE ObjectType)
	Allocates a object.

PVOID	PhReferenceObject (_In_ PVOID Object)
	References the specified object.

_May_raise_ LONG	PhReferenceObjectEx (_In_ PVOID Object, _In_ LONG RefCount)
	References the specified object.

BOOLEAN	PhReferenceObjectSafe (_In_ PVOID Object)
	Attempts to reference an object and fails if it is being destroyed.

VOID	PhDereferenceObject (_In_ PVOID Object)
	Dereferences the specified object.

BOOLEAN	PhDereferenceObjectDeferDelete (_In_ PVOID Object)
	Dereferences the specified object.

_May_raise_ LONG	PhDereferenceObjectEx (_In_ PVOID Object, _In_ LONG RefCount, _In_ BOOLEAN DeferDelete)
	Dereferences the specified object.

PPH_OBJECT_TYPE	PhGetObjectType (_In_ PVOID Object)
	Gets an object's type.

PPH_OBJECT_TYPE	PhCreateObjectType (_In_ PWSTR Name, _In_ ULONG Flags, _In_opt_ PPH_TYPE_DELETE_PROCEDURE DeleteProcedure)
	Creates an object type.

PPH_OBJECT_TYPE	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.

VOID	PhGetObjectTypeInformation (_In_ PPH_OBJECT_TYPE ObjectType, _Out_ PPH_OBJECT_TYPE_INFORMATION Information)
	Gets information about an object type.

PPH_OBJECT_HEADER	PhpAllocateObject (_In_ PPH_OBJECT_TYPE ObjectType, _In_ SIZE_T ObjectSize)
	Allocates storage for an object.

VOID	PhpFreeObject (_In_ PPH_OBJECT_HEADER ObjectHeader)
	Calls the delete procedure for an object and frees its allocated storage.

VOID	PhpDeferDeleteObject (_In_ PPH_OBJECT_HEADER ObjectHeader)
	Queues an object for deletion.

NTSTATUS	PhpDeferDeleteObjectRoutine (_In_ PVOID Parameter)
	Removes and frees objects from the to-free list.

PVOID	PhCreateAlloc (_In_ SIZE_T Size)
	Creates a reference-counted memory block.

FORCEINLINE PPH_AUTO_POOL	PhpGetCurrentAutoPool (VOID)
	Gets the current auto-dereference pool for the current thread.

_May_raise_ FORCEINLINE VOID	PhpSetCurrentAutoPool (_In_ PPH_AUTO_POOL AutoPool)
	Sets the current auto-dereference pool for the current thread.

VOID	PhInitializeAutoPool (_Out_ PPH_AUTO_POOL AutoPool)
	Initializes an auto-dereference pool and sets it as the current pool for the current thread.

_May_raise_ VOID	PhDeleteAutoPool (_Inout_ PPH_AUTO_POOL AutoPool)
	Deletes an auto-dereference pool.

VOID	PhDrainAutoPool (_In_ PPH_AUTO_POOL AutoPool)
	Dereferences and removes all objects in an auto-release pool.

_May_raise_ PVOID	PhAutoDereferenceObject (_In_opt_ PVOID Object)
	Adds an object to the current auto-dereference pool for the current thread.

VOID	PhaDereferenceObject (PVOID Object)
	Deprecated.

Variables
PPH_OBJECT_TYPE	PhObjectTypeObject = NULL

SLIST_HEADER	PhObjectDeferDeleteListHead

PH_FREE_LIST	PhObjectSmallFreeList

PPH_OBJECT_TYPE	PhAllocType = NULL

ULONG	PhObjectTypeCount = 0

PPH_OBJECT_TYPE	PhObjectTypeTable [PH_OBJECT_TYPE_TABLE_SIZE]

Macro Definition Documentation

#define _PH_REF_PRIVATE

Definition at line 23 of file ref.c.

#define REF_STAT_UP ( Name ) PHLIB_INC_STATISTIC(Name)

Definition at line 44 of file ref.c.

Function Documentation

VOID PhaDereferenceObject ( PVOID Object )

Deprecated.

Use PhAutoDereferenceObject instead.

Definition at line 768 of file ref.c.

_May_raise_ PVOID 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.

PVOID 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_ PVOID 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.

PPH_OBJECT_TYPE 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.

PPH_OBJECT_TYPE 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_ VOID 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.

VOID 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.

BOOLEAN 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_ LONG 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.

VOID 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.

PPH_OBJECT_TYPE 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.

VOID 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.

VOID 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.

PPH_OBJECT_HEADER PhpAllocateObject	(	_In_ PPH_OBJECT_TYPE	ObjectType,
		_In_ SIZE_T	ObjectSize
	)

Allocates storage for an object.

Parameters

ObjectType	The type of the object.
ObjectSize	The size of the object, excluding the header.

Definition at line 450 of file ref.c.

VOID PhpDeferDeleteObject ( _In_ PPH_OBJECT_HEADER ObjectHeader )

Queues an object for deletion.

Parameters

ObjectHeader A pointer to the object header of the object to delete.

Definition at line 535 of file ref.c.

NTSTATUS PhpDeferDeleteObjectRoutine ( _In_ PVOID Parameter )

Removes and frees objects from the to-free list.

Definition at line 555 of file ref.c.

VOID PhpFreeObject ( _In_ PPH_OBJECT_HEADER ObjectHeader )

Calls the delete procedure for an object and frees its allocated storage.

Parameters

ObjectHeader A pointer to the object header of an allocated object.

Definition at line 487 of file ref.c.

FORCEINLINE PPH_AUTO_POOL PhpGetCurrentAutoPool ( VOID )

Gets the current auto-dereference pool for the current thread.

Definition at line 593 of file ref.c.

_May_raise_ FORCEINLINE VOID PhpSetCurrentAutoPool ( _In_ PPH_AUTO_POOL AutoPool )

Sets the current auto-dereference pool for the current thread.

Definition at line 603 of file ref.c.

PVOID 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_ LONG 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.

BOOLEAN 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.

Variable Documentation

PPH_OBJECT_TYPE PhAllocType = NULL

Definition at line 31 of file ref.c.

SLIST_HEADER PhObjectDeferDeleteListHead

Definition at line 29 of file ref.c.

PH_FREE_LIST PhObjectSmallFreeList

Definition at line 30 of file ref.c.

ULONG PhObjectTypeCount = 0

Definition at line 33 of file ref.c.

PPH_OBJECT_TYPE PhObjectTypeObject = NULL

Definition at line 28 of file ref.c.

PPH_OBJECT_TYPE PhObjectTypeTable[PH_OBJECT_TYPE_TABLE_SIZE]

Definition at line 34 of file ref.c.

Macros

Functions

Variables

Macro Definition Documentation

Function Documentation

Variable Documentation