interface IDisposable in Tinman.Core.System

Base interface for classes whose objects hold resources (object references, GPU memory, file handles, monitors, etc.) and need to be disposed explicitly.

interface	IDisposable	extends	ILifecycleState
		base of	Disposable
			IApplication
			ICanvasContent
			ICanvasFactory
			IConnection
			IDataStream
			IEvent
			IFile
			IFileSystem
			IImageReader
			IImageWriter
			IInitializable
			IMapEntity
			IMesh
			IModelReader
			INativeHandle
			IOperation
			IResource
			IResourceCache
			IResourceData
			IServer
			IShaderEffect
			IShaderTechnique
			IShapeReader
			ISimpleHttp
			ITextStream
			IThreadMain
			IVertexUpdater

Remarks

The following figure illustrates the state transitions an IDisposable object undergoes during its lifecycle (see LifecycleState):

 ##            +-------------+
#### --------> | Initialized |
 ##   ctor()   +-------------+
                     |
                     | Dispose()
                     v
               +-------------+
               |  Disposing  |
               +-------------+            ##
               |  Disposed   | --------> #  #
               +-------------+  ~dtor()   ##

After instantiation, the object is in state Initialized, in which it serves its purposes and can be used without limitations. The object can be disposed by calling the Dispose method. Upon disposal, the object releases all held resources and switches to state Disposing/Disposed. Object deletion is performed automatically after disposal (via smart pointers in C++, via garbage collection in C# and Java). If an object is deleted without having been disposed before, the Dispose method is invoked; this situation should be avoided in C# and Java, since finalizer/destructor calls can happen at any time and from within any thread.

An IDisposable object has an implicit ownership concept: The first owner of a disposable object is the code that has created it

The constructor of a class implementing the IDisposable interface should look like the following:

ClassName()
{
  // Initialize variables to NULL values here (applies to C++ only).
  try
  {
    // Constructor code here.
  }
  catch(<any exception>)
  {
    Dispose();
    throw;
  }
}

This will ensure that all system resources allocated by constructor code will be released properly even if the constructor throws an exception, thereby leaving an incomplete object.

Since the Dispose method may be called on incomplete objects, the disposal code cannot assume that all resources have been allocated; instead every single resource must be checked if it is not NULL and then be disposed (this is why they must be initialized to NULL values:

void Dispose()
{
  if (resourceA != <null>)
  {
    // Release resourceA.
    resourceA = <null>;
  }

  if (resourceB != <null>)
  {
    // Release resourceB.
    resourceB = <null>;
    }

  // etc...
}

Attributes

LifecycleState

Returns the lifecycle state of this object.

property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	ILifecycleState.LifecycleState

Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
method	Dispose ()

Remarks:

The Dispose method silently returns if the object has already been disposed.

Extensions

Acquire

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
method	Acquire ()
type	IDisposable
returns		[not-null]	The strong reference to this disposable object.

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls this method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Exceptions:

• TinmanException:
  If the given object is no longer valid.

ThrowIfDisposed

Throws an exception if this disposable object has been disposed or is being disposed.

method

ThrowIfDisposed ()

Exceptions:

• TinmanException:
  If this object is no longer valid.