Difference between revisions of "Documentation/DevGuide/ProUNO/acquire() and release()"

Revision as of 20:59, 3 July 2018

Every UNO interface is derived from com.sun.star.uno.XInterface:

  // module com::sun::star::uno
  interface XInterface
  {
      any queryInterface( [in] type aType ); 
      [oneway] void acquire(); 
      [oneway] void release(); 
  };

UNO objects must maintain an internal reference counter. Calling acquire() on a UNO interface increases the reference count by one. Calling release() on UNO interfaces decreases the reference count by one. If the reference count drops to zero, the UNO object may be destroyed. Destruction of an object is sometimes called death of an object or that the object dies. The reference count of an object must always be non-negative.

Once acquire() is called on the UNO object, there is a reference or a hard reference to the object, as opposed to a weak reference. Calling release() on the object is often called releasing or clearing the reference.

The UNO object does not export the state of the reference count, that is, acquire() and release() do not have return values. Generally, the UNO object should not make any assumptions on the concrete value of the reference count, except for the transition from one to zero.

The invocation of a method is allowed first when acquire () has been called before. For every call to acquire(), there must be a corresponding release call, otherwise the object leaks.

The UNO Java binding encapsulates acquire() and release() in the UnoRuntime.queryInterface() call. The same applies to the Reference<> template in C++. As long as the interface references are obtained through these mechanisms, acquire() and release() do not have to be called in your programs.