Structive/docs/CORE_GUIDE.md

Structive Property Core Guide

中文

1. Include and CMake target

#include <structive/property/property.hpp>

target_link_libraries(my_target PRIVATE structive::property_core)

Property Core is C++20.

2. Define a managed object

using namespace structive;
struct Device : Property_Object<Device> {
    double temperature{25.0};
    double pressure{101.3};
    int serial_number{1001};
};

Property_Object<Device> adds managed operations. The fields remain ordinary members.

3. Define the type descriptor

template <>
struct structive::Type_Descriptor<Device> {
    static auto get() {
        return object<Device>(
            synchronization(sync_all_independent),
            field<&Device::temperature>(
                key<"temperature">,
                unit<"C">,
                min_value<-50.0>,
                max_value<200.0>
            ),
            field<&Device::pressure>(
                key<"pressure">,
                unit<"kPa">
            ),
            field<&Device::serial_number>(
                key<"serial_number">,
                read_only
            )
        );
    }
};

The descriptor is the structural definition of Device.

4. Schema guarantees

A valid schema guarantees:

• every registered property has a non-empty key;
• keys are unique;
• member selectors belong to the described object type;
• single-valued Attribute categories are not duplicated on the same property;
• capability metadata cannot request operations unsupported by the underlying accessor;
• constraints are compatible with the property value type.

Use:

static_assert(Property_Described_Object<Device>);
using Schema = type_descriptor_schema_t<Device>;
static_assert(Valid_Property_Schema<Schema>);

5. Access the schema

const auto& schema = type_descriptor<Device>();
const auto& same_schema = device.schema();

Properties can be selected by index or member pointer:

const auto& first = schema.property<0>();
const auto& temperature = schema.property<&Device::temperature>();

6. Property descriptor information

A property descriptor exposes compile-time structural facts:

using Property = std::remove_cvref_t<decltype(schema.property<&Device::temperature>())>;
static_assert(Property::readable);
static_assert(Property::writable);
static_assert(Property::runtime_copy_writable);
using Value = Property::value_type;
using Accessor = Property::accessor_type;

A read_only field reports:

using Serial = std::remove_cvref_t<decltype(schema.property<&Device::serial_number>())>;
static_assert(Serial::readable);
static_assert(!Serial::writable);

The key is available at runtime without dynamic allocation:

auto key_value = schema.property<&Device::temperature>().key();

7. Intrinsic capability

Core capability values are:

Property_Capability::none
Property_Capability::read
Property_Capability::write
Property_Capability::read_write

Convenience Attributes are:

read_only
write_only
read_write
inaccessible

The capability belongs to the property itself. It is not an authorization rule.

If capability metadata is absent, Structive derives capability from the accessor.

For a normal non-const member field, the default is read/write.

For a getter-only computed property, the default is read-only.

Capability metadata can narrow the accessor, but it cannot create an operation the accessor does not support.

8. No access-control API

Property Core intentionally does not provide access modes or domain views.

There is no built-in distinction between:

internal
external
persistence

A consumer decides its own policy. For example, a GUI may choose to expose only selected properties even though all of them are structurally readable.

Core only exposes intrinsic readable and writable facts.

9. Core Attributes

9.1 Key

Every property requires one key:

key<"temperature">

The key is the structural protocol identifier used by runtime lookup and adapters.

9.2 Capability

read_only
write_only
read_write
inaccessible

Capability Attributes are single-valued and non-inheritable.

9.3 Unit

unit<"C">
unit<"kPa">

Core stores unit metadata but does not perform conversion.

9.4 Sensitive

sensitive<>
sensitive<false>

sensitive is inheritable metadata. It does not implement authorization. A consumer may use it as one input to its own policy.

10. Custom Attributes and defaults

Any type following the Attribute protocol can be attached to a property.

struct Group_Category {};
template <Fixed_String Value>
struct Group_Attribute {
    using attribute_category = Group_Category;
    static constexpr bool single_valued = true;
    static constexpr bool inheritable = true;
    static constexpr auto value = Value;
};

Inheritable Attributes can be supplied by defaults(...):

object<Device>(
    defaults(sensitive<>),
    field<&Device::temperature>(key<"temperature">)
)

Capability is intentionally non-inheritable because each property owns its intrinsic operation set.

11. Constraints and validation

Built-in constraints include:

min_value<0>
max_value<100>
finite

Custom constraints:

constraint<"even">([](int value) {
    return value % 2 == 0;
})

Validation is explicit:

auto result = validate_property_value<&Device::temperature>(device.schema(), candidate);
if (result) {
    auto key_value = result->property_key;
    auto code = result->code;
}

write() does not automatically call validation.

12. Typed managed read/write

Member-pointer access is the preferred C++ API:

auto temperature = device.read<&Device::temperature>();
device.write<&Device::temperature>(30.0);

Compile-time key access is also available:

auto temperature = device.read<"temperature">();
device.write<"temperature">(30.0);

The typed interfaces are constrained by intrinsic capability. A write to read_only does not participate in overload resolution.

template <class Object>
concept Can_Write_Serial = requires(Object& object) {
    object.template write<&Device::serial_number>(1);
};
static_assert(!Can_Write_Serial<Device>);

13. Read-only fast path

Stored read-only properties are statically removed from managed locking.

Given:

field<&Device::serial_number>(key<"serial_number">, read_only)

Structive resolves:

serial_number -> unsynchronized_slot

and read<&Device::serial_number>() does not query a lock slot or construct a shared_lock.

This remains true even when the broad default is sync_all_shared.

If an object has only stored read-only properties, those properties contribute zero mutexes to resolved_synchronization().lock_count.

14. Synchronization plans

Synchronization is intentionally a topology layer rather than a property permission system. It answers only one question: when managed mutable state is accessed concurrently, which properties share a consistency domain?

Stored intrinsic read-only properties are removed before lock slots are materialized. A broad rule such as sync_all_shared therefore never creates a mutex merely for a stored read_only property.

14.1 Default topologies

Default	Meaning for properties that require synchronization
sync_all_independent	each property receives its own lock domain
sync_all_shared	all properties share one lock domain
sync_all_unsynchronized	no real lock domain is created

synchronization(sync_all_independent)

sync_all_unsynchronized is an explicit opt-out. Structive still provides managed access, but the caller owns the thread-safety consequences of concurrent reads and writes.

14.2 Compile-time member rules

Use member pointers when the schema is known in C++ code:

synchronization(
    sync_all_shared,
    sync_independent<&Device::temperature>(),
    sync_unsynchronized<&Device::debug_counter>()
)

Member validity is checked while the synchronization specification is materialized for the schema.

14.3 Runtime-key rules

Adapters or configuration code may build a Synchronization_Plan from keys:

Synchronization_Plan plan;
plan.set_default(Synchronization_Default::independent);
plan.unsynchronized("debug_counter");

Key validity cannot be known until the plan is resolved. Unknown properties, duplicate property configuration, empty groups and duplicate group names are rejected with std::invalid_argument.

14.4 Groups are consistency domains

synchronization(
    sync_all_independent,
    sync_group<&Device::min_speed, &Device::max_speed>("speed_range")
)

Members in one group resolve to the same lock slot if they actually require synchronization. A read-only stored member may appear in a broad rule or group, but it still resolves to unsynchronized_slot because there is no managed writer to protect.

A group should express a real invariant or snapshot boundary. It should not be used merely to reduce the mutex count.

14.5 Why the synchronization API has several forms

The forms represent different information availability, not duplicate concepts:

• type-level defaults describe the normal topology once per object type;
• compile-time member rules give typed C++ code compile-time schema checking;
• runtime-key rules support adapters that discover property names dynamically;
• per-instance overrides support objects whose synchronization topology genuinely differs from the type default;
• guards express a temporary multi-property consistency operation.

The common semantic model is always the same resolved lock-slot topology.

15. Per-instance synchronization override

An object can explicitly override the type default:

Device device{
    property_synchronization(
        synchronization(sync_all_shared)
    )
};

For typed member rules:

Device device{
    property_synchronization<Device>(
        synchronization(
            sync_all_independent,
            sync_group<&Device::temperature, &Device::pressure>("environment")
        )
    )
};

The default topology is resolved once and shared per type. Only an object with an explicit override stores a compact override layout. Copy and move construction preserve an object's override topology; assignment preserves the destination object's existing topology because assignment changes object state, not the synchronization policy chosen for that instance.

16. Inspect resolved synchronization

auto view = device.resolved_synchronization();
auto count = view.lock_count;

Inspect a member slot:

auto slot = device.lock_slot<&Device::temperature>();

No-lock properties use:

Resolved_Synchronization_View::unsynchronized_slot

For a stored read-only property this is automatic. resolved_synchronization() and lock_slot() are primarily diagnostics and framework-level inspection APIs; normal business code should usually express its intent through read, write, lock_shared and lock_unique instead of reasoning about numeric slots.

17. Static multi-property guards

Read guard:

auto guard = device.lock_shared<&Device::temperature, &Device::pressure>();
auto by_member = guard.get<&Device::temperature>();
auto by_key = guard.get<"pressure">();

Write guard:

auto guard = device.lock_unique<&Device::min_speed, &Device::max_speed>();
guard.set<&Device::min_speed>(20);
guard.set<"maximum_speed">(120);

Member and compile-time-key access intentionally use the same get/set names. Capability constraints are part of the overload itself: a typed unique guard cannot be requested for a read-only property, and set does not exist for a non-writable property in a requires expression.

Static guards resolve member slots, deduplicate repeated domains and acquire locks in stable numeric slot order. Request order therefore does not become mutex acquisition order, avoiding lock-order inversion when two callers request the same domains in different member order.

A read-only stored property may participate in a shared guard's logical held set without introducing a mutex. This allows a guard API to read it consistently with its intrinsic contract while preserving the read-only zero-lock fast path.

18. Dynamic-key guards

auto read_guard = device.lock_shared({"temperature", "pressure"});
auto write_guard = device.lock_unique({"temperature", "pressure"});
auto value = read_guard.get<"temperature">();

Dynamic guards exist for callers whose selected property set is known only at runtime. Because the keys are dynamic, errors that typed guards reject through constraints become runtime errors:

• an unknown key throws std::invalid_argument;
• lock_shared rejects a non-readable property;
• lock_unique rejects a non-writable property;
• a later get/set throws std::logic_error if the requested property is outside the guard's held set.

Dynamic and static guards use the same resolved lock topology and the same stable lock ordering.

The behavior above is covered directly by core/tests/synchronization_test.cpp, including independent/shared/unsynchronized defaults, groups, overrides, invalid plans, runtime-key guards, blocking behavior and reversed member-order acquisition.

19. Traversal

Schema-only traversal:

schema.for_each_property([&](auto index, const auto& descriptor) {
});

Readable value traversal:

device.for_each_readable([&](auto index, const auto& descriptor, const auto& value) {
});

Locked readable traversal:

device.for_each_readable_locked([&](auto index, const auto& descriptor, const auto& value) {
});

The locked traversal acquires only actual synchronization slots. Read-only stored properties do not introduce locks.

Writable transaction-style guard acquisition:

device.with_all_writable_locked([&](auto& guard) {
});

This acquires all writable managed lock domains; it does not perform validation or rollback automatically.

20. Computed properties

A synchronized computed property receives a read view:

computed_property<Device, int>([](const auto& view) {
    return view.template get<&Device::max_speed>() - view.template get<&Device::min_speed>();
}, key<"speed_span">)

Writable dependencies that must form one snapshot should share the computed synchronization domain:

synchronization(
    sync_all_independent,
    sync_group("speed", "min_speed", "max_speed", "speed_span")
)

A read-only stored dependency may be read through the computed view without joining a lock slot, because it has no managed writer.

21. Trusted accessor properties

Trusted getter:

trusted_computed_property<&Device::value>(key<"value">)

Trusted getter/setter:

trusted_accessor_property<&Device::get_value, &Device::set_value>(key<"value">)

These forms access the object directly rather than using synchronized dependency views. They should only be used when the caller understands the synchronization contract of those member functions.

22. Runtime type-erased access

Property_Object_Base is the dynamic adapter boundary. It is intended for GUI inspectors, serialization adapters, scripting bridges, RPC layers and other code that learns a property key only at runtime. Normal typed C++ code should prefer read and write.

Property_Object_Base& erased = device;

Introspection:

erased.runtime_object_type();
erased.runtime_property_count();

22.1 Runtime read

auto result = erased.runtime_read("temperature", context, callback);

On success the callback is invoked exactly once with the schema index, key, exact type_info and a pointer to the current value. The value pointer is borrowed and is valid only during the callback; copy or consume it synchronously and never retain it.

For a synchronized writable property, Structive keeps the corresponding managed read lock held while the callback executes. The callback should therefore not re-enter a conflicting managed write on the same lock domain. A stored read-only property follows the intrinsic zero-lock fast path and does not acquire a mutex merely because the access is dynamic.

22.2 Runtime write

auto result = erased.runtime_write("temperature", typeid(double), &value);

Runtime write intentionally performs no implicit conversion. typeid(double) must exactly match the property's declared value type, and the pointer must address a live value of that exact type for the duration of the call. The boundary copies from a const input. If a writable accessor cannot accept that copy input, its descriptor exposes runtime_copy_writable == false and runtime access returns unsupported_runtime_write; typed write still accepts move-only values when the accessor supports them. A successful runtime write uses the same managed synchronization path as typed write.

22.3 Result contract

Result	Meaning
ok	lookup and access completed
unknown_property	no schema property has that runtime key
not_readable	the property exists but its intrinsic capability is not readable
not_writable	the property exists but its intrinsic capability is not writable
unsupported_runtime_write	the property is intrinsically writable but its accessor cannot accept the runtime copy-input boundary
type_mismatch	runtime write supplied a type different from the declared property value type

There is no external/persistence access mode and no access-control policy in this API. An adapter decides whether it wants to expose or call runtime read/write; Structive reports only the property's intrinsic capability.

22.4 Why this API is deliberately low-level

The runtime boundary uses type_info, void* and a callback because the value type is unknown to the caller at compile time. Core does not impose a universal variant, heap-owned any, serialization format or conversion registry, because any of those would add ownership and conversion policy that belongs to a higher-level adapter.

This is therefore an adapter API rather than the preferred business-code API. A higher-level extension may wrap it in domain-specific value containers without changing Structive Core.

The contract is covered directly by core/tests/runtime_api_test.cpp, including every result code, callback metadata, exact-type writes, managed blocking behavior and the read-only zero-lock runtime fast path.

23. Lock policies

Default:

Property_Object<Device, Shared_Mutex_Policy>

No-lock:

Property_Object<Device, No_Lock_Policy>

No_Lock_Policy stores no real mutex array and avoids real lock objects on managed hot paths.

24. Raw object access

Device& raw = device.unsafe_object();

or normal public member access:

device.temperature = 30.0;

Both bypass the Structive managed contract.

This is intentional. Structive is cooperative structural infrastructure, not forced encapsulation.

25. Recommended usage rules

Use these defaults:

1. Use ordinary C++ members for storage.
2. Register only fields that belong to the structural model.
3. Prefer member-pointer typed APIs in C++ business code.
4. Use read_only when the Structive managed model must never write a stored property.
5. Rely on the resulting zero-lock optimization for stored read-only data.
6. Keep raw writes to read-only properties outside concurrent managed code.
7. Use synchronization groups for mutable cross-field consistency.
8. Keep validation explicit.
9. Use runtime access only for genuinely dynamic adapters.
10. Let GUI/RPC/persistence/authorization layers own their own exposure and access policy.