Class SafeWorkerParentValue<T>

A thread-safe wrapper for custom worker and worker system properties that support setting and getting values, and will also throw if the worker or worker system has an unexpected (configurable) state (e.g. that it has already been started) when the value is accessed. Use this to ensure safe access by other threads and to disallow accessing unpopulated or partially populated values.

Also see Public Properties etc. and its example.

Use one of the Set methods in a public setter to allow the user to set a property value that the worker or worker system uses.

Use SetValueUnchecked(T) inside your worker or worker system to set a result value before it has completed.

Use one of the Get methods in a public getter to allow the user to get a property value that the worker or worker system has provided.

Use GetValueUnchecked() inside your worker or worker system to get a value that the user has set.

Note that to provide thread-safety, all accesses to the value are synchronized, which have a small overhead. If using the value many times internally in the WorkerParent during the running phase, e.g. for each dataflow row, consider only calling GetValueUnchecked() or SetValueUnchecked(T) once during the running phase, by caching the value in a local variable.

Note: All methods in this class are thread-safe.

Note: If you don't need to check the WorkerParentStatus, consider using Interlocked instead to read and write values, since it has slightly lower overhead.

Inheritance

Object

SafeWorkerParentValue<T>

Namespace: actionETL

Assembly: actionETL.dll

Syntax

public class SafeWorkerParentValue<T>

Type Parameters

Name	Description
T	The type to be initialized.

Constructors

SafeWorkerParentValue(WorkerParent)

Initializes a new instance of the SafeWorkerParentValue<T> class.

Note that the wrapped value will not have a default value, even if it is a value type; one of the Set* methods must be used to set a value.

Declaration

public SafeWorkerParentValue(WorkerParent workerParent)

Parameters

Type	Name	Description
WorkerParent	workerParent	The worker or worker system this value belongs to.

Exceptions

Type	Condition
ArgumentNullException	workerParent

SafeWorkerParentValue(WorkerParent, T)

Initializes a new instance of the SafeWorkerParentValue<T> class, with a default value.

Declaration

public SafeWorkerParentValue(WorkerParent workerParent, T value)

Parameters

Type	Name	Description
WorkerParent	workerParent	The worker or worker system this value belongs to.
T	value	The starting value.

Exceptions

Type	Condition
ArgumentNullException	workerParent

Properties

HasValue

Returns true if a value has been set; otherwise false.

Declaration

public bool HasValue { get; }

Property Value

Type	Description
Boolean

Methods

GetValueChecked(WorkerParentState[])

Gets the value if the value has been set and the WorkerParent has one of the specified states; otherwise throws. Use this method in a WorkerParent public getter property to e.g. expose the WorkerParent result.

Declaration

public T GetValueChecked(params WorkerParentState[] allowedWorkerParentStates)

Parameters

Type	Name	Description
WorkerParentState[]	allowedWorkerParentStates	The allowed worker parent states.

Returns

Type	Description
T

Exceptions

Type	Condition
InvalidOperationException	Cannot get the value when the WorkerParent state is not one of the specified states. Value not set.

GetValueUnchecked()

Gets the value (if it's been set), irrespective of the WorkerParent state. Use this method in a WorkerParent public getter property to expose a value that is always available.

This method can also be used to get the value internally in the WorkerParent when you know it's safe to do so, which avoids the overhead of checking the WorkerParent status.

Declaration

public T GetValueUnchecked()

Returns

Type	Description
T

Exceptions

Type	Condition
InvalidOperationException	No value set.

GetValueWhenCompleted()

Gets the value if the value has been set and the WorkerParent has completed; otherwise throws. Use this method in a WorkerParent public getter property to expose values that are set by the WorkerParent, even when it receives a failed status.

This method is a shorthand for: GetValueChecked(WorkerParentState.Succeeded, WorkerParentState.Canceled, WorkerParentState.Error, WorkerParentState.Fatal).

Declaration

public T GetValueWhenCompleted()

Returns

Type	Description
T

Exceptions

Type	Condition
InvalidOperationException	Value only available after the WorkerParent has completed successfully. Value not set.

GetValueWhenNotRunning()

Gets the value if the value has been set and the WorkerParent has is not running; otherwise throws. Use this method in a WorkerParent public getter property to expose a WorkerParent value that has a valid value both before running, and after completing. Note that this requires setting a value in the WorkerParent constructor.

This method is a shorthand for: GetValueChecked(WorkerParentState.Created, WorkerParentState.Succeeded, WorkerParentState.Canceled, WorkerParentState.Error, WorkerParentState.Fatal).

Declaration

public T GetValueWhenNotRunning()

Returns

Type	Description
T

Exceptions

Type	Condition
InvalidOperationException	Value not available when the WorkerParent is running. Value not set.

GetValueWhenSucceeded()

Gets the value if the value has been set and the WorkerParent has completed successfully; otherwise throws. Use this method in a WorkerParent public getter property to expose the WorkerParent result.

This method is a shorthand for: GetValueChecked(WorkerParentState.Succeeded).

Declaration

public T GetValueWhenSucceeded()

Returns

Type	Description
T

Exceptions

Type	Condition
InvalidOperationException	Value only available after the WorkerParent has completed successfully. Value not set.

SetValueChecked(T, WorkerParentState[])

Sets the value if the WorkerParent is in one of the specified states; otherwise throws.

This can e.g. be used to allow the WorkerParent user to set the value before it runs (e.g. to set a default value), and/or after it has completed (e.g. to remove a reference to a class instance).

Declaration

public void SetValueChecked(T value, params WorkerParentState[] allowedWorkerParentStates)

Parameters

Type	Name	Description
T	value	The value.
WorkerParentState[]	allowedWorkerParentStates	The allowed worker parent states.

Exceptions

Type	Condition
InvalidOperationException	No allowed states specified. Cannot set the value when the WorkerParent state is not one of the specified states.

SetValueUnchecked(T)

Sets the value, irrespective of the WorkerParent state. It is still thread-safe, however. Use this method internally in the WorkerParent to set the result.

Declaration

public void SetValueUnchecked(T value)

Parameters

Type	Name	Description
T	value	The value.

SetValueWhenNotRunning(T)

Sets the value if the WorkerParent is not running; otherwise throws. This method is a shorthand for: SetValueChecked(value, WorkerParentState.Created, WorkerParentState.Succeeded, WorkerParentState.Canceled, WorkerParentState.Error, WorkerParentState.Fatal).

This can be used to allow the WorkerParent user to set the value either before it runs (e.g. to set a default value), or after it has completed (e.g. to remove a reference to a class instance).

Declaration

public void SetValueWhenNotRunning(T value)

Parameters

Type	Name	Description
T	value	The value.

Exceptions

Type	Condition
InvalidOperationException	Cannot set the value when the WorkerParent state is not one of the specified states.

ToString()

Returns a string that represents this instance.

Declaration

public override string ToString()

Returns

Type	Description
String

Overrides

Object.ToString()