ref_iface_IVDXUnknown_Release - shekh/VirtualDub2 GitHub Wiki

VirtualDub Plugin SDK 1.2

IVDXUnknown interface

IVDXUnknown:: Release

Decrements the reference count on an object and destroys it if the reference count is zero.

int Release();

Thread safety

This method is not thread-safe.

Errors

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

Return value

A non-negative value indicating the new reference count on the object. A return value of zero indicates that the object was destroyed.

Remarks

The IVDXUnknown::Release() method is very similar to the IUnknown::Release() method in the Microsoft Component Object Model (COM). It is used to drop an independent strong reference on the object; the object is automatically destroyed when all strong references are gone.

As Release() may be called more widely than the other methods on an object, initialization or other types of nontrivial processing must not be done in Release(). Release() 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::Release() {
    int newRefCount = (int)InterlockedDecrement(&mRefCount);
    if (!newRefCount)
        delete this;
    return newRefCount;
}

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

An implementation of Release() must not read an internal reference count variable more than once, as this can lead to failures. The following implementation is incorrect:

int MyClass::Release() {
    int newRefCount = (int)InterlockedDecrement(&mRefCount);

    // This is incorrect, as two threads may see mRefCount go to zero, causing the
    // object to be destroyed twice.
    if (!mRefCount)
        delete this;
    
    // This is incorrect, as the reference count variable may be read after the enclosing
    // object is destroyed.
    return mRefCount;
}