Class CachedStorage

Namespace

OptunaSharp.Storages

Assembly

OptunaSharp.dll

A wrapper class of storage backends. Port of optuna/storages/_cached_storage.py: _CachedStorage (public in C# so the satellite RDB packages can compose with it).

Data persistence — this class does not guarantee that write operations are logged into a persistent storage, even when write methods succeed. Thus, when process failure occurs, some writes might be lost. As exceptions, when a persistent storage is available, any writes on any attributes of Study and writes on state of Trial are guaranteed to be persistent. Additionally, any preceding writes on any attributes of Trial are guaranteed to be written into a persistent storage before writes on state of Trial succeed. The same applies for param, user_attrs, system_attrs and intermediate_values attributes.

public class CachedStorage : BaseStorage, IBaseHeartbeat

Inheritance

object

BaseStorage

CachedStorage

Implements

IBaseHeartbeat

Inherited Members

BaseStorage.DefaultStudyNamePrefix

BaseStorage.SetStudyUserAttr(int, IReadOnlyDictionary<string, object>)

BaseStorage.SetStudySystemAttr(int, IReadOnlyDictionary<string, object>)

BaseStorage.GetTrialNumberFromId(int)

BaseStorage.GetTrialParam(int, string)

BaseStorage.SetTrialUserAttr(int, IReadOnlyDictionary<string, object>)

BaseStorage.SetTrialSystemAttr(int, IReadOnlyDictionary<string, object>)

BaseStorage.GetNTrials(int, IReadOnlyCollection<TrialState>)

BaseStorage.GetTrialParams(int)

BaseStorage.GetTrialUserAttrs(int)

BaseStorage.GetTrialSystemAttrs(int)

BaseStorage.RemoveSession()

BaseStorage.CheckTrialIsUpdatable(int, TrialState)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

CachedStorage(BaseStorage)

Wraps an RDB-compatible backend with a synchronized cache.

public CachedStorage(BaseStorage backend)

Parameters

backend BaseStorage

Shared backend implementing ICachedStorageBackend; the wrapper does not own its lifetime.

Exceptions

ArgumentException

The backend does not implement ICachedStorageBackend.

Properties

Backend

The wrapped backend.

public BaseStorage Backend { get; }

Property Value

BaseStorage

Methods

CreateNewStudy(IReadOnlyList<StudyDirection>, string?)

Create a new study from a name. If no name is specified, the storage class generates a name. The returned study ID is unique among all current and deleted studies.

public override int CreateNewStudy(IReadOnlyList<StudyDirection> directions, string? studyName = null)

Parameters

directions IReadOnlyList<StudyDirection>

Objective directions in the same order as the objective values.

studyName string

Name identifying the study in the selected storage.

Returns

int

Unique storage identifier assigned to the created study.

Exceptions

DuplicatedStudyError

If a study with the same name already exists.

CreateNewTrial(int, FrozenTrial?)

Create and add a new trial to a study. The returned trial ID is unique among all current and deleted trials.

public override int CreateNewTrial(int studyId, FrozenTrial? templateTrial = null)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

templateTrial FrozenTrial

Template FrozenTrial with default user-attributes, system-attributes, intermediate-values, and a state.

Returns

int

Unique storage identifier of the created trial.

Exceptions

KeyError

If no study with the matching ID exists.

DeleteStudy(int)

Delete a study.

public override void DeleteStudy(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Exceptions

KeyError

If no study with the matching ID exists.

GetAllStudies()

Read a list of FrozenStudy objects, sorted by study ID.

public override List<FrozenStudy> GetAllStudies()

Returns

List<FrozenStudy>

Study metadata records ordered by storage identifier.

GetAllTrials(int, bool, IReadOnlyCollection<TrialState>?)

Read all trials in a study, sorted by trial ID.

public override List<FrozenTrial> GetAllTrials(int studyId, bool deepcopy = true, IReadOnlyCollection<TrialState>? states = null)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

deepcopy bool

Whether to copy trial records; treat records returned with false as read-only.

states IReadOnlyCollection<TrialState>

States to include; null includes every state.

Returns

List<FrozenTrial>

Trials in identifier order, optionally filtered by state and copied.

Exceptions

KeyError

If no study with the matching ID exists.

GetBestTrial(int)

Return the trial with the best value in a study. Valid only during single-objective optimization.

public override FrozenTrial GetBestTrial(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

FrozenTrial

Best completed single-objective trial by objective value; feasibility is handled by Study.

Exceptions

KeyError

If no study with the matching ID exists.

RuntimeError

If the study has more than one direction.

ValueError

If no trials have been completed.

GetHeartbeatInterval()

Reads the configured heartbeat period.

public int? GetHeartbeatInterval()

Returns

int?

Heartbeat interval in seconds, or null when disabled.

GetHeartbeatStaleTrialCallback()

Reads the callback used after a stale trial is failed.

public Action<Study, FrozenTrial>? GetHeartbeatStaleTrialCallback()

Returns

Action<Study, FrozenTrial>

Configured callback, or null if no stale-trial callback is registered.

GetStaleTrialIds(int)

Finds running trials whose heartbeat exceeds the backend grace period.

public List<int> GetStaleTrialIds(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

List<int>

Identifiers of running trials considered stale by the backend.

GetStudyDirections(int)

Read whether a study maximizes or minimizes an objective.

public override List<StudyDirection> GetStudyDirections(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

List<StudyDirection>

Objective directions in objective-value order; callers must not mutate shared storage records.

Exceptions

KeyError

If no study with the matching ID exists.

GetStudyIdFromName(string)

Read the ID of a study.

public override int GetStudyIdFromName(string studyName)

Parameters

studyName string

Name identifying the study in the selected storage.

Returns

int

Storage identifier of the named study.

Exceptions

KeyError

If no study with the matching name exists.

GetStudyNameFromId(int)

Read the study name of a study.

public override string GetStudyNameFromId(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

string

Registered study name.

Exceptions

KeyError

If no study with the matching ID exists.

GetStudySystemAttrs(int)

Read the optuna-internal attributes of a study.

public override OrderedDict<string, object?> GetStudySystemAttrs(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

OrderedDict<string, object>

Internal metadata snapshot; callers must not mutate shared storage records.

Exceptions

KeyError

If no study with the matching ID exists.

GetStudyUserAttrs(int)

Read the user-defined attributes of a study.

public override OrderedDict<string, object?> GetStudyUserAttrs(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

OrderedDict<string, object>

User metadata snapshot; callers must not mutate shared storage records.

Exceptions

KeyError

If no study with the matching ID exists.

GetTrial(int)

Read a trial.

public override FrozenTrial GetTrial(int trialId)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

Returns

FrozenTrial

Stored trial record; treat it as read-only unless copied.

Exceptions

KeyError

If no trial with the matching ID exists.

GetTrialIdFromStudyIdTrialNumber(int, int)

Read the trial ID of a trial.

public override int GetTrialIdFromStudyIdTrialNumber(int studyId, int trialNumber)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

trialNumber int

Zero-based trial number within the study, not a storage identifier.

Returns

int

Storage identifier corresponding to the per-study trial number.

Exceptions

KeyError

If no trial with the matching study ID and trial number exists.

ArgumentOutOfRangeException

The trial number is negative.

GetTrialsPrefixView(int)

Read all trials of a study as a fixed-membership, zero-copy window when the backend can afford one — the O(1) sibling of GetAllTrials(deepcopy: false) for samplers that consult history on every ask (a per-ask list copy makes the optimization loop quadratic in trial count). The window's membership is frozen at the call; each read returns the trial's current snapshot.

public override IReadOnlyList<FrozenTrial> GetTrialsPrefixView(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

IReadOnlyList<FrozenTrial>

Trials in identifier order; treat the collection and its records as read-only. The base implementation falls back to GetAllTrials(deepcopy: false), so backends without a live in-memory list keep their existing (copying) behavior and only InMemoryStorage-like backends get the O(1) path.

Remarks

Synchronizes with the backend exactly as GetAllTrials(int, bool, IReadOnlyCollection<TrialState>?) does, then wraps the number-ordered cache in a TrialsPrefixView instead of sorting and copying it (Rustuna plan 13, item S10): the genetic samplers take this view on every ask, which made each ask O(n log n) on a database storage. The view holds the same records GetAllTrials(deepcopy: false) would return, in the same order; a later synchronization can replace an unfinished trial's record with a fresher one, which a read of the view then returns, as the view's contract says.

When a trial number is not cached yet (another worker's trial a sync has not brought in), the view could not be indexed by number, so the copying read is used instead, as before.

Exceptions

KeyError

If no study with the matching ID exists.

RecordHeartbeat(int)

Persists the latest liveness timestamp for a running trial.

public void RecordHeartbeat(int trialId)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

Exceptions

Exception

The heartbeat storage provider fails.

SetStudySystemAttr(int, string, object?)

Register an optuna-internal attribute to a study, overwriting any existing value.

public override void SetStudySystemAttr(int studyId, string key, object? value)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

key string

Attribute name; a later write replaces its stored value.

value object

Attribute value; persistent backends require JSON-serializable data.

Exceptions

KeyError

If no study with the matching ID exists.

SetStudySystemAttrs(int, IReadOnlyDictionary<string, object?>)

Register several optuna-internal attributes to a study at once (Rustuna's set_study_system_attrs; plan 13, item S8): the result of SetStudySystemAttr(int, string, object?) once per entry, in order.

public override void SetStudySystemAttrs(int studyId, IReadOnlyDictionary<string, object?> attrs)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order.

Remarks

The default writes one entry per call; see SetStudyUserAttrs(int, IReadOnlyDictionary<string, object?>) for what the overrides do.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no study with the matching ID exists.

SetStudyUserAttr(int, string, object?)

Register a user-defined attribute to a study, overwriting any existing value.

public override void SetStudyUserAttr(int studyId, string key, object? value)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

key string

Attribute name; a later write replaces its stored value.

value object

Attribute value; persistent backends require JSON-serializable data.

Exceptions

KeyError

If no study with the matching ID exists.

SetStudyUserAttrs(int, IReadOnlyDictionary<string, object?>)

Register several user-defined attributes to a study at once, overwriting existing values (Rustuna's set_study_user_attrs; Rustuna plan 13, item S8). Optuna has no such call: the result is what calling SetStudyUserAttr(int, string, object?) once per entry, in the dictionary's order, leaves.

public override void SetStudyUserAttrs(int studyId, IReadOnlyDictionary<string, object?> attrs)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order.

Remarks

This default writes one entry per call, exactly as a caller looping over SetStudyUserAttr(int, string, object?) would, so any storage supports it; it is atomic only as far as each single call is. The built-in storages override it to write in one step: one lock in memory, one appended batch in a journal, one transaction in a database. An empty dictionary writes nothing and checks nothing.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no study with the matching ID exists.

SetTrialIntermediateValue(int, long, double)

Report an intermediate value of an objective function, overwriting any existing value associated with the step.

public override void SetTrialIntermediateValue(int trialId, long step, double intermediateValue)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

step long

Reporting step whose intermediate objective observation is stored.

intermediateValue double

Intermediate objective observation to store at the reporting step.

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialParam(int, string, double, BaseDistribution)

Set a parameter to a trial.

public override void SetTrialParam(int trialId, string paramName, double paramValueInternal, BaseDistribution distribution)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

paramName string

Parameter name used as the storage and distribution lookup key.

paramValueInternal double

Parameter value in the distribution's internal numeric representation.

distribution BaseDistribution

Distribution defining the parameter representation and allowed values.

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

ValueError

The distribution is incompatible with an existing parameter distribution.

SetTrialStateValues(int, TrialState, IReadOnlyList<double>?)

Update the state and values of a trial. If values is not null, this method overwrites any existing trial values.

public override bool SetTrialStateValues(int trialId, TrialState state, IReadOnlyList<double>? values = null)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

state TrialState

Trial state to record or inspect.

values IReadOnlyList<double>

Objective values in study direction order, or null when no objective values are recorded.

Returns

bool

true if the state is successfully updated; false if the state is kept the same (which happens when updating a RUNNING trial to RUNNING).

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialSystemAttr(int, string, object?)

Set an optuna-internal attribute to a trial, overwriting any existing value.

public override void SetTrialSystemAttr(int trialId, string key, object? value)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

key string

Attribute name; a later write replaces its stored value.

value object

Attribute value; persistent backends require JSON-serializable data.

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialSystemAttrs(int, IReadOnlyDictionary<string, object?>)

Set several optuna-internal attributes of a trial at once (Rustuna's set_trial_system_attrs; plan 13, item S8): the result of SetTrialSystemAttr(int, string, object?) once per entry, in order.

public override void SetTrialSystemAttrs(int trialId, IReadOnlyDictionary<string, object?> attrs)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order.

Remarks

The default writes one entry per call; see SetTrialUserAttrs(int, IReadOnlyDictionary<string, object?>) for what the overrides do.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialUserAttr(int, string, object?)

Set a user-defined attribute to a trial, overwriting any existing value.

public override void SetTrialUserAttr(int trialId, string key, object? value)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

key string

Attribute name; a later write replaces its stored value.

value object

Attribute value; persistent backends require JSON-serializable data.

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialUserAttrs(int, IReadOnlyDictionary<string, object?>)

Set several user-defined attributes of a trial at once, overwriting existing values (Rustuna's set_trial_user_attrs; Rustuna plan 13, item S8). Optuna has no such call: the result is what calling SetTrialUserAttr(int, string, object?) once per entry, in the dictionary's order, leaves.

public override void SetTrialUserAttrs(int trialId, IReadOnlyDictionary<string, object?> attrs)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order.

Remarks

This default writes one entry per call, as a caller's own loop would, so any storage supports it; a failure part-way leaves the entries before it written. The built-in storages override it to write in one step and check the trial once, so a finished or unknown trial gets nothing written: one lock in memory, one appended batch of ordinary single-attribute records in a journal (what Python's journal reader expects), one transaction in a database. An empty dictionary writes nothing and checks nothing.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.