TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

interface IOperation in Tinman.Core.Threading.Operations

Base interface that can be run via the RunningOperation class.

interface IOperation extends IConfigurable
  IDisposable
  IOperationOps
  IValidatable
  base of IMapProjectionOperation
  Operation

Remarks

A class that implements the IOperation interface performs a lengthy task. Typically, this task will be executed in a background thread. Running background operations are represented by instances of the RunningOperation class.

A running background operation provides its current progress via an IProgressMonitor object that has been passed to its Run method.

When a background operation is executed, the following tasks are performed:

  1. The Run method is called and the operation performs the actual work, providing the its current progress using the given IProgressMonitor object.
  2. After the background operation has ended (finished, failed or cancelled), it is disposed (see Dispose). Cleanup should be performed there.

See also:

IProgressMonitor
RunningOperation

Attributes

IsSoleOwnership

Will this object be disposed upon the next call to Dispose?

[ThreadSafe]
property IsSoleOwnership { get }
type bool
value true if the object will be disposed when Dispose is called,
false if the object will not be disposed, because some other code is still holding shared ownership (see AcquireBase).
inherited IDisposable.IsSoleOwnership

LifecycleState

Returns the lifecycle state of this object.

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

Name

Returns the human-readable name of this background operation.

property Name { get }
type string
value [not-null] The name.

ShallCancel

Shall the background operation cancel?

property ShallCancel { get }
type bool
value true if the operation shall cancel, false if not.

Remarks:

Once Cancel has been called, this property will return true.

Weight

The weight of this operation.

property Weight { get }
type int32
value [0..100] The weight of this operation.

Remarks:

This value is only used for reporting progress when combining multiple operations.

Methods

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
method AcquireBase (bool allowNull = false)
type IDisposable
params allowNull Depicts what to do when this object is no longer valid:
true: return null
false: throw an exception
returns The strong reference to this disposable object or null iff allowNull is true and this object is no longer valid.
inherited IDisposable.AcquireBase

Remarks:

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

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

Using this method usually requires type casting. Subclasses may additionally implement IDisposableGeneric, in order to provide some syntactic sugar for that.

Exceptions:

And

Returns an IOperation object that simultaneously executes this operation and the given one.

[OwnerReturn, OwnerThis]
method And ([Owner] IOperation operation)
type IOperation
params operation The other operation. If null, this will be returned.
returns [not-null] The resulting IOperation object.
inherited IOperationOps.And

Cancel

Requests that the running background operation gracefully terminates.

method Cancel ()

Remarks:

An IOperation is free to honor a cancel request or to ignore it. Cancelling a background operation should be considered as a hint to terminate as soon as possible.

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 ()
inherited IDisposable.Dispose

Remarks:

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

Implementing methods must not throw any exceptions.

Run

Runs the operation.

method Run (IProgressMonitor progress)
params progress [not-null] The progress monitor object to use.

Remarks:

If an exception resp. error occurs, it will be reported via Error, and the Run method will return.

Then

Returns an IOperation object that executes this operation, followed by the given operation.

[OwnerReturn, OwnerThis]
method Then ([Owner] IOperation operation)
type IOperation
params operation The other operation. If null, this will be returned.
returns [not-null] The resulting IOperation object.
inherited IOperationOps.Then

ToConfig

Returns the configuration value that describes this object.

method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
inherited IConfigurable.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

Exceptions:

Validate

Validates the state of this object.

method Validate (Validator validator)
params validator [not-null] The validator object.
inherited IValidatable.Validate

Extensions

RunBackground

Runs the operation in a new background thread.

[OwnerReturn, OwnerThis]
method RunBackground ()
type RunningOperation
returns [not-null] The RunningOperation object that represents the running background operation.

RunSync

Runs the operation synchronously in the calling thread.

[OwnerThis]
method RunSync ()

Exceptions:

RunTerminal

Runs the operation in a new background thread blocks the calling thread until it has finished, while displaying a simple progress indicator in the console.

[OwnerThis]
method RunTerminal ()
type TinmanError
returns The error if the background operation has failed, null if it has finished successfully.

Remarks:

This method is intended to be used for testing.