Class TrialsPrefixView

Namespace

OptunaSharp.Storages

Assembly

OptunaSharp.dll

A zero-copy, fixed-length window over the first Count trials of a study's live trial list — what GetTrialsPrefixView(int) returns. Constructing one is O(1) where GetAllTrials(deepcopy: false) is O(N) (it copies the list), which is the difference between a linear and a quadratic optimization loop for samplers that consult history on every ask.

public sealed class TrialsPrefixView : IReadOnlyList<FrozenTrial>, IReadOnlyCollection<FrozenTrial>, IEnumerable<FrozenTrial>, IEnumerable

Inheritance

object

TrialsPrefixView

Implements

IReadOnlyList<FrozenTrial>

IReadOnlyCollection<FrozenTrial>

IEnumerable<FrozenTrial>

IEnumerable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Liveness. The window's membership is frozen (indices 0..Count-1 at creation time — appends after creation are invisible), but each read returns the trial's current record: a storage that replaces a trial's record on update is seen through this view at its latest state, unlike a copied list whose elements go stale. Samplers want exactly that — the freshest attrs of a frozen membership.

In-memory records. InMemoryStorage writes a running trial's record in place while no reader holds it (plan 13, item S4), so this view reads an unfinished record under the storage's lock and marks it as held: the storage copies it before its next write, and the record the caller got never changes. A finished record is never written again, so it is read without the lock.

Footgun — concurrency. Reads are lock-free against a backing List<T> whose element writes are atomic reference stores, so reading while elements are replaced is safe; reading while the list is growing (a resize moves the backing array) is safe only because a resize replaces the array atomically and indices below Count exist in both copies. Do not use this view to observe trials being appended concurrently — take it after the mutation, as the samplers do (one ask/tell at a time per study).

Constructors

TrialsPrefixView(List<FrozenTrial>, int)

Wraps the first count elements of trials.

public TrialsPrefixView(List<FrozenTrial> trials, int count)

Parameters

trials List<FrozenTrial>

The live storage list; borrowed, never mutated through this view.

count int

The frozen membership size; must not exceed the list's length at any read.

Exceptions

ArgumentNullException

trials is null.

ArgumentOutOfRangeException

count is negative.

Properties

Count

The frozen membership size — appends to the backing list after construction are not visible.

public int Count { get; }

Property Value

int

this[int]

The current snapshot of trial number index (trial numbers equal list positions).

public FrozenTrial this[int index] { get; }

Parameters

index int

Zero-based trial position, below Count.

Property Value

FrozenTrial

The trial's latest stored instance (copy-on-write storages update it in place of older instances).

Exceptions

ArgumentOutOfRangeException

index is outside the frozen window.

Methods

GetEnumerator()

Enumerates the frozen window front to back, reading current instances.

public IEnumerator<FrozenTrial> GetEnumerator()

Returns

IEnumerator<FrozenTrial>

An enumerator over the first Count trials.