IEntry

IEntry<Response> is interface for classes that hold result object. Entry is also used for tracking the build process of a value, and as cache container.

IEntry is interface for accessing basic information.

/// <summary>Holds and caches a value.</summary>
public interface IEntry
{
    /// <summary>Current status</summary>
    EntryStatus Status { get; }
    /// <summary>Policy flags</summary>
    EntryPolicy Policy { get; set; }
    /// <summary>Processing thread id. 0=unassigned.</summary>
    int ThreadId { get; set; }
}

IEntryReadable is interface for reading entry state.

/// <summary>Indiciates that entry is readable.</summary>
public interface IEntryReadable : IEntry
{
    /// <summary>Error</summary>
    Exception? Error { get; }
    /// <summary>Snapshot of state</summary>
    EntryState State { get; }
    /// <summary>Entry value as object.</summary>
    object? Value { get; }
}

IEntryReadable<T> is for reading as T.

/// <summary>Readable entry of <typeparamref name="T"/> value.</summary>
public interface IEntryReadable<out T> : IEntryReadableT
{
    /// <summary>Entry value as <typeparamref name="T"/>.</summary>
    new T Value { get; }
}

IEntryWritable is for writing entry state.

/// <summary>Indiciates that entry is writable.</summary>
public interface IEntryWritable : IEntry
{
    /// <summary>Try to mark entry into processing state. Only one thread may reserve the processing state. The thread that gets the state must complete the entry into <see cref="EntryStatus.Completed"/> state, and other threads must wait for it.</summary>
    /// <returns>True if state changed from <see cref="EntryStatus.Unassigned"/> to <see cref="EntryStatus.Processing"/></returns>
    /// <exception cref="Exception">Unexpected error (from an observer)</exception>
    bool TrySetProcessing();

    /// <summary>Try dispose associated value.</summary>
    /// <exception cref="Exception">Unexpected error (from an observer)</exception>
    bool TrySetCanceled();

    /// <summary>Try to assign <see cref="EntryStatus.NoValue"/> state.</summary>
    /// <exception cref="Exception">Unexpected error (from an observer)</exception>
    bool TrySetNoValue();

    /// <summary>Try to assign <paramref name="value"/>.</summary>
    /// <exception cref="Exception">Unexpected error (from an observer)</exception>
    bool TrySetValue(object? value);

    /// <summary>Try to assign default value, e.g. null</summary>
    /// <exception cref="Exception">Unexpected error (from an observer)</exception>
    bool TrySetValueDefault();

    /// <summary>Try to assign <paramref name="errorValue"/> and set state to <see cref="EntryStatus.Error"/>.</summary>
    /// <exception cref="Exception">Unexpected error (from an observer)</exception>
    bool TrySetError(Exception errorValue);

    /// <summary>Assign <paramref name="error"/> and set state to <see cref="EntryStatus.UnexpectedError"/>.</summary>
    /// <exception cref="Exception">Unexpected error (from an observer)</exception>
    bool TrySetUnexpectedError(Exception error);

    /// <summary>Assign flags.</summary>
    /// <exception cref="Exception">Unexpected error (from an observer)</exception>
    bool TrySetFlags(EntryStatus flagsToInclude, EntryStatus flagsToExclude);

    /// <summary>
    /// Try to dispose associated value.
    /// Entry must be in <see cref="EntryStatus.Value"/> state.
    /// If value implements <see cref="IDisposable"/> it's called, if not then function succeeds.
    /// If dispose fails, then exception is let to fly, and state is not changed.
    /// 
    /// If dispose was successful or value did not implement <see cref="IDisposable"/> then state is changed to <see cref="EntryStatus.ValueDisposed"/>.
    /// </summary>
    /// <exception cref="AggregateException">Any exception thrown from <see cref="IDisposable.Dispose"/> or observers.</exception>
    bool TryDisposeValue();

    /// <summary>
    /// Try to the reference to the associated value. 
    /// Entry must be in <see cref="EntryStatus.Value"/>, <see cref="EntryStatus.Error"/>, <see cref="EntryStatus.UnexpectedError"/> or <see cref="EntryStatus.ValueDisposed"/> state.
    /// If value has not been dispose, this method does not dispose it. 
    /// 
    /// If value is not nullable then default value is set. 
    /// State of entry is set to <see cref="EntryStatus.ValueNulled"/>.
    /// </summary>
    /// <exception cref="Exception">Any exception thrown from observers.</exception>
    bool TryNullValue();
}

IEntryWritable<T> is for writing value as T.

/// <summary>Writable entry for <typeparamref name="T"/> values.</summary>
public interface IEntryWritable<in T> : IEntryWritableT
{
    /// <summary>Assign <paramref name="value"/>.</summary>
    bool TrySetValue(T value);
}

Usage

Entry<T> is the default implementation.

// Create entry
IEntry<string> entry = new Entry<string>();

.SetProcessing() marks entry into Processing state.

// Set processing
entry.SetProcessing();

.SetValue() assigns a value.

// Set value
entry.SetValue("Result");

.SetError() assigns an error state.

// Set error result
entry.SetError(new NotSupportedException());

.SetQueryError() assigns an unexpected error (cathed from handler).

// Set unexpected error
entry.SetUnexpectedError(new InvalidOperationException());

.Dispose() disposes entry and value.

// Disepose entry and value
((IDisposable)entry).Dispose();

Full Example

Full example

using System;
using System.Threading;
using Avalanche.Service;
using static System.Console;

public class entry_entry
{
    public static void Run()
    {
        {
            // <01>
            // Create entry
            IEntry<string> entry = new Entry<string>();
            // </01>
            // Print status
            WriteLine(entry.Status); // "Unassigned"
        }
        {
            // Create entry
            IEntry<string> entry = new Entry<string>();
            // <02>
            // Set processing
            entry.SetProcessing();
            // </02>
            // Print status
            WriteLine(entry.Status); // "Processing"
        }
        {
            // Create entry
            IEntry<string> entry = new Entry<string>();
            // <03>
            // Set value
            entry.SetValue("Result");
            // </03>
            // Print status
            WriteLine(entry.Status); // "Value"
        }
        {
            // Create entry
            IEntry<string> entry = new Entry<string>();
            // <04>
            // Set error result
            entry.SetError(new NotSupportedException());
            // </04>
            // Print status
            WriteLine(entry.Status); // "Error"
        }
        {
            // Create entry
            IEntry<string> entry = new Entry<string>();
            // <05>
            // Set unexpected error
            entry.SetUnexpectedError(new InvalidOperationException());
            // </05>
            // Print status
            WriteLine(entry.Status); // "UnexpectedError"
        }
        {
            // Create entry
            IEntry<Semaphore> entry = new Entry<Semaphore>(EntryPolicy.Default);
            // Set value
            entry.SetValue(new Semaphore(1, 1));
            // <06>
            // Disepose entry and value
            ((IDisposable)entry).Dispose();
            // </06>
            // Print status
            WriteLine(entry.Status); // "Disposed"
        }
    }
}