Releasing Objects in UMDF

NTDEV
1

Hi,
I have noticed in the FX2 sample that there are several ways to release an object:

  1. SAFE_RELEASE(FxRequest);
  2. FxRequest->DeleteWdfObject();
  3. fxMemory->Release();
    What is the difference between the different release methods and why do some of them appear in the same function (isn’t one release enough?)?
    I’ve also noticed that releasing of an object is sometimes only in the scope of the function. For instance, a request is “released” in OnRead, but is referred to again in OnCompletion.
    Thanks,
    Gadi
2

SAFE_RELEASE is a macro which calls IUnknown::Release, so #1 and #3 are
the same thing. SAFE_RELEASE checks for NULL so we use it cases where
we would have to check before releasing the pointer.

So that means there are only two concepts in play here:

  1. Reference Counting
  2. Object “State”

Reference counting is used in UMDF the same way it’s used in COM - it
provides bookkeeping so that you know how many aliases (pointers) you
have to the object at any one time, with the theory that the object
can’t be freed until all those pointers are gone. IWDF* interfaces
remain valid as long as there’s an outstanding reference on them -
meaning that you can call their methods without hitting an unallocated
pointer. However whether you can actually do anything with the object
depends on whether it’s been deleted.

WDF maintains a tree of objects internally, and uses a combination of
internal and external triggers to determine when an object is no longer
needed. For example, a request the I/O manager sends you is no longer
needed once it’s been completed. When the object is no longer needed
then that object and all of its child objects are removed from the
object tree, their cleanup routines are run, and they all enter the
‘deleted’ state. However the objects stick around until their reference
counts drop to zero they will be freed from memory.

There are times when you don’t want an object to stick around until its
parent is destroyed. Say you allocate a request to send to the lower
driver. When that request completes you want to delete it since it’s no
longer useful (in KMDF you could reuse it, UMDF doesn’t support that
unfortunate). This is what the DeleteWdfObject method is for. When you
call it on a request you allocated request and any child objects (say a
memory object that goes with it) will get cleanup callbacks. Then when
your driver releases it reference on the request it will be freed.

Object state is a very permanent change to an object, while reference
counting is a transient way of saying “don’t invalidate that pointer
just yet”

-p

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of xxxxx@n-trig.com
Sent: Thursday, March 08, 2007 6:47 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] Releasing Objects in UMDF

Hi,
I have noticed in the FX2 sample that there are several ways to release
an object:

  1. SAFE_RELEASE(FxRequest);
  2. FxRequest->DeleteWdfObject();
  3. fxMemory->Release();
    What is the difference between the different release methods and why do
    some of them appear in the same function (isn’t one release enough?)?
    I’ve also noticed that releasing of an object is sometimes only in the
    scope of the function. For instance, a request is “released” in OnRead,
    but is referred to again in OnCompletion.
    Thanks,
    Gadi

Questions? First check the Kernel Driver FAQ at
http://www.osronline.com/article.cfm?id=256

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

3

To further emphasize what Peter said, the COM interface model has no explicit delete this object call. The generic deletion/freeing of the interface is implicit and is performed on the last dereference of the interface. In WDF, implicit delete is not a part of the object model. Objects are explicitly deleted (through a Delete interface call or Delete API call depending on which framework). This means that you cannot explicitly delete a UMDF object that you created just by calling Release() on it. The same is true for KMDF as well with the additional caveat that if you delete the object through a dereference() call instead of deleteobject(), the framework will bugcheck the machine.

d