IUnknown_AtomicRelease

This function provides some common code for simultaneously releasing an interface and clearing the interface pointer.

Declaration

VOID IUnknown_AtomicRelease (PVOID *ppunk);

Parameters

The ppunk argument provides the address at which the caller holds an interface pointer.

Behaviour

If the ppunk argument is not NULL and produces an interface pointer that is not NULL, then the function first clears the interface pointer and then releases the interface.

This function offers a consistent coding of a sequence that appears frequently in almost all projects that use COM interfaces.

ISomeInterface *p = SomeInterfacePointer;
SomeInterfacePointer = NULL;
if (p != NULL) p -> Release ();

Each such sequence can instead be coded as

IUnknown_AtomicRelease ((PVOID *) &SomeInterfacePointer);

Among the benefits are: an appreciable saving of space in the executable, when the few bytes saved per instance accumulate through frequent repetition; and some assurance that a program does not erroneously remember interface pointers that it has released.

Availability

The IUnknown_AtomicRelease function is exported from SHLWAPI.DLL as ordinal 169 in version 5.00 and higher.

Though this function dates from as long ago as 1999, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.

However, the function did eventually get documented, apparently later in 2004. This article now conforms to Microsoft’s nomenclature.