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	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

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

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.
inherited	IDisposable.AcquireTry

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.

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	[not-null]	The other operation.
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.

Run

Runs the operation.

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

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	[not-null]	The other operation.
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.

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.

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.