ref_iface_IVDXUnknown_AddRef - shekh/VirtualDub2 GitHub Wiki

VirtualDub Plugin SDK 1.2

IVDXUnknown interface

IVDXUnknown:: AddRef

Increments the reference count on an object.

int AddRef();

Thread safety

This method is not thread-safe.

Errors

Errors may not be returned from this function (see SetError()).

Return value

A non-zero positive value indicating the new reference count on the object.

Remarks

The IVDXUnknown::AddRef() method is very similar to the IUnknown::AddRef() method in the Microsoft Component Object Model (COM). It is used to obtain an independent strong reference on the object, such that the object is not destroyed until all strong references on the object are gone. Each call to AddRef() on an object must have a matching call to Release().

As AddRef() may be called more widely than the other methods on an object, initialization or other types of nontrivial processing must not be done in AddRef(). AddRef() must not call into any callbacks within the host, nor may it fail.

It is vitally important that the reference count be maintained in a thread-safe manner, as AddRef() and Release() may be called from multiple threads even on an object whose functional methods are not thread-safe. The simplest way to do this is through the InterlockedIncrement() and InterlockedDecrement() methods in the Win32 Platform SDK:

int MyClass::AddRef() {
    return (int)InterlockedIncrement(&mRefCount);
}

In Visual C++, the _InterlockedIncrement() and _InterlockedDecrement() intrinsics may be used.