Skip to navigation
API referenceC++ APIClasses

holoscan::ParamFieldBuilder

Beta
View as Markdown
template <typename ParamsT, auto MemberPtr>
class ParamFieldBuilder

Build one compile-time field declaration for an exact aggregate member.

The builder is a transient constant-evaluation value. It registers nothing, stores no object address, and is not thread-shared at runtime. Invalid combinations make schema lowering fail.

#include <holoscan/parameter_schema.hpp>

Template parameters

ParamsT
typename

Exact aggregate owning MemberPtr.

MemberPtr
auto

Exact non-static data-member pointer.

Constructors

ParamFieldBuilder

holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::ParamFieldBuilder(
    std::string_view canonical_name
) noexcept

Create a field declaration with default compile-time/public/persisted policies.

Parameters

canonical_name
std::string_view

Nonempty valid UTF-8 structured path with static lifetime.

Methods

description

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::description(
    std::string_view text
) noexcept

Attach descriptive field metadata.

Returns: This builder.

Parameters

text
std::string_view

Valid UTF-8 text with static lifetime.

unit

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::unit(
    std::string_view text
) noexcept

Attach a descriptive unit name.

Returns: This builder.

Parameters

text
std::string_view

Valid UTF-8 unit text with static lifetime.

compile_time

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::compile_time() noexcept

Require a newly compiled plan for changes after compile.

Returns: This builder.

runtime_mutable

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::runtime_mutable() noexcept

Declare eligibility for separately admitted immutable generation updates.

Returns: This builder; the marker grants no update authority by itself.

lifecycle_mutable

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::lifecycle_mutable(
    LifecycleStage stage = LifecycleStage::kConfigure
) noexcept

Declare a lifecycle transaction from the earliest invalidated forward stage.

Returns: This builder; invalid teardown or unknown stages fail schema lowering.

Parameters

stage
LifecycleStageDefaults to LifecycleStage::kConfigure

Forward stage from kConfigure through kStart.

recompile_required

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::recompile_required() noexcept

Require a newly compiled plan for every value change.

Returns: This builder.

range

template <typename Minimum, typename Maximum>
ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::range(
    Minimum minimum,
    Maximum maximum
)

Add an inclusive finite range in the field’s exact scalar domain.

Returns: This builder; reversed, non-finite, or mismatched bounds fail lowering.

Template parameters

Minimum
typename

Exact field type, or a duration convertible to the field’s duration domain.

Maximum
typename

Exact field type, or a duration convertible to the field’s duration domain.

Parameters

minimum
Minimum

Inclusive finite lower bound; duration conversion must be representable, with integral fields requiring an exact tick.

maximum
Maximum

Inclusive finite upper bound; duration conversion must be representable, with integral fields requiring an exact tick.

allowed_values

template <typename T>
ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::allowed_values(
    std::initializer_list<T> values
)

Add a fixed-capacity allowed-value set in the exact scalar domain.

Returns: This builder; overflow, non-finite, or mismatched values fail lowering.

Template parameters

T
typename

Exact field type.

Parameters

values
std::initializer_list<T>

Up to 16 finite values copied during constant evaluation.

enum_values

template <typename EnumT>
ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::enum_values(
    std::initializer_list<NamedParamEnumValue<EnumT>> values
)

Declare the bounded stable label/value domain of an enum field.

Returns: This builder; the declared domain is also the allowed-value constraint.

Template parameters

EnumT
typename

Exact direct, optional, or sequence-element enum type.

Parameters

values
std::initializer_list<NamedParamEnumValue<EnumT>>

Up to 16 unique labels and values copied during constant evaluation.

validator

template <auto Validator>
ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::validator(
    std::string_view stable_validator_id
) noexcept

Attach a named process-local side-effect-free Boolean validator.

Returns: This builder.

Template parameters

Validator
auto

Noexcept bool(const ``Field``&) callable known at compile time.

Parameters

stable_validator_id
std::string_view

Nonempty stable UTF-8 identity exported without the callable.

persistence

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::persistence(
    ParamPersistence policy
) noexcept

Select the durable-projection policy explicitly.

Returns: This builder; conflicting repeated selections fail lowering.

Parameters

policy
ParamPersistence

Persisted or transient disposition to record as authored evidence.

persisted

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::persisted() noexcept

Mark the field eligible for policy-filtered durable projection.

Returns: This builder; conflicting with transient() fails lowering.

transient

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::transient() noexcept

Exclude the field from every ordinary durable projection.

Returns: This builder; conflicting with persisted() fails lowering.

internal

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::internal() noexcept

Hide the field from ordinary local discovery.

Returns: This builder; internality does not imply sensitivity.

external_access

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::external_access(
    ParamExternalAccess policy
) noexcept

Select the external-access policy explicitly.

Returns: This builder; conflicting repeated selections fail lowering.

Parameters

policy
ParamExternalAccess

None, read-only, or tuning eligibility; this grants no authority or codec.

external_read_only

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::external_read_only() noexcept

Declare eligibility for separately authorized external reads.

Returns: This builder; no authority or codec is granted.

external_tuning

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::external_tuning() noexcept

Declare eligibility for separately authorized external tuning.

Returns: This builder; runtime mutability and non-sensitive public visibility are required.

sensitivity

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::sensitivity(
    ParamSensitivity policy
) noexcept

Select the sensitivity/redaction policy explicitly.

Returns: This builder; conflicting repeated selections fail lowering.

Parameters

policy
ParamSensitivity

Normal or sensitive disposition to record as authored evidence.

sensitive

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::sensitive() noexcept

Require ordinary projection to redact before value access.

Returns: This builder.

required_on_load

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::required_on_load() noexcept

Require an archived contribution during future complete import.

Returns: This builder; no loader is implemented by this declaration.

alias

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::alias(
    std::string_view prior_name
) noexcept

Add one prior canonical migration input name.

Returns: This builder; aliases never become output identity.

Parameters

prior_name
std::string_view

Nonempty valid UTF-8 prior identity with static lifetime.

encoding

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::encoding(
    ParamStringEncoding encoding
) noexcept

Declare semantic encoding for a std::string field.

Returns: This builder; UTF-8 bounds require kUtf8 explicitly.

Parameters

encoding
ParamStringEncoding

KArbitraryBytes or kUtf8.

element_encoding

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::element_encoding(
    ParamStringEncoding encoding
) noexcept

Declare semantic encoding for each std::string sequence element.

Returns: This builder; per-element UTF-8 bounds require kUtf8 explicitly.

Parameters

encoding
ParamStringEncoding

KArbitraryBytes or kUtf8.

max_utf8_bytes

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::max_utf8_bytes(
    std::size_t maximum
) noexcept

Bound valid UTF-8 storage for a std::string field.

Returns: This builder; zero or a non-string field fails lowering.

Parameters

maximum
std::size_t

Positive byte count.

max_element_utf8_bytes

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::max_element_utf8_bytes(
    std::size_t maximum
) noexcept

Bound valid UTF-8 bytes for each std::string sequence element.

Returns: This builder; zero, another field type, or omitted UTF-8 element policy rejects.

Parameters

maximum
std::size_t

Positive byte count per element.

max_elements

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::max_elements(
    std::size_t maximum
) noexcept

Bound the element count of a std::vector field.

Returns: This builder; zero or a non-vector field fails lowering.

Parameters

maximum
std::size_t

Positive element count.

max_encoded_bytes

ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::max_encoded_bytes(
    std::size_t maximum
) noexcept

Bound encoded bytes for a string, vector, path, or codec-qualified field.

Returns: This builder; zero or an inapplicable field fails lowering.

Parameters

maximum
std::size_t

Positive encoded byte count.

nested

template <typename NestedParamsT>
ParamFieldBuilder & holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::nested() noexcept

Bind this exact object field to its already declared nested schema.

Returns: This builder; nested identity participates in parent hashes.

Template parameters

NestedParamsT
typename

Exact field type with a declared schema.

invalid

bool holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::invalid() const noexcept

Return whether the accumulated declaration violates a static schema rule.

Returns: true for an invalid declaration; intended for consteval schema lowering.

reset_lifecycle_state

void holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::reset_lifecycle_state() noexcept

run_custom_validator

template <auto Validator>
static bool holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::run_custom_validator(
    const void *aggregate
) noexcept

validate_field

static ParamValidationResult holoscan::ParamFieldBuilder<ParamsT, MemberPtr>::validate_field(
    const void *aggregate,
    const ParamFieldDescriptor &descriptor
) noexcept

Types

Typedefs

NameDefinitionDescription
Traitsdetail::MemberPointerTraits< decltype(MemberPtr)>Expose member-pointer traits for compile-time schema lowering.
Fieldtypename Traits::FieldName the exact declared field type.
Ownertypename Traits::OwnerName the exact owning aggregate type.

Member variables

NameTypeDescription
canonical_name_std::string_view
description_std::string_view
unit_std::string_view
validator_id_std::string_view
alias_std::string_view
mutability_ParamMutability
earliest_invalidated_stage_LifecycleStage
persistence_ParamPersistence
string_encoding_ParamStringEncoding
element_string_encoding_ParamStringEncoding
visibility_ParamVisibility
external_access_ParamExternalAccess
sensitivity_ParamSensitivity
constraints_ParamConstraints
enum_choices_ParamEnumChoices
persistence_explicit_bool
external_access_explicit_bool
sensitivity_explicit_bool
persistence_conflict_bool
external_access_conflict_bool
sensitivity_conflict_bool
required_on_load_bool
nested_bool
invalid_lifecycle_stage_bool
invalid_range_bool
invalid_allowed_value_bool
invalid_constraint_bool
invalid_enum_choice_bool
too_many_allowed_values_bool
custom_validator_bool(*
kEnumField static constexprbool