# Structive Property Core Guide [中文](CORE_GUIDE.zh-CN.md) ## 1. Include and CMake target ```cpp #include ``` ```cmake target_link_libraries(my_target PRIVATE structive::property_core) ``` Property Core is C++20. ## 2. Define a managed object ```cpp using namespace structive; struct Device : Property_Object { double temperature{25.0}; double pressure{101.3}; int serial_number{1001}; }; ``` `Property_Object` adds managed operations. The fields remain ordinary members. ## 3. Define the type descriptor ```cpp template <> struct structive::Type_Descriptor { static auto get() { return object( 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: ```cpp static_assert(Property_Described_Object); using Schema = type_descriptor_schema_t; static_assert(Valid_Property_Schema); ``` ## 5. Access the schema ```cpp const auto& schema = type_descriptor(); const auto& same_schema = device.schema(); ``` Properties can be selected by index or member pointer: ```cpp 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: ```cpp using Property = std::remove_cvref_t())>; 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: ```cpp using Serial = std::remove_cvref_t())>; static_assert(Serial::readable); static_assert(!Serial::writable); ``` The key is available at runtime without dynamic allocation: ```cpp auto key_value = schema.property<&Device::temperature>().key(); ``` ## 7. Intrinsic capability Core capability values are: ```cpp Property_Capability::none Property_Capability::read Property_Capability::write Property_Capability::read_write ``` Convenience Attributes are: ```cpp 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: ```text 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: ```cpp key<"temperature"> ``` The key is the structural protocol identifier used by runtime lookup and adapters. ### 9.2 Capability ```cpp read_only write_only read_write inaccessible ``` Capability Attributes are single-valued and non-inheritable. ### 9.3 Unit ```cpp unit<"C"> unit<"kPa"> ``` Core stores unit metadata but does not perform conversion. ### 9.4 Sensitive ```cpp sensitive<> sensitive ``` `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. ```cpp struct Group_Category {}; template 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(...)`: ```cpp object( 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: ```cpp min_value<0> max_value<100> finite ``` Custom constraints: ```cpp constraint<"even">([](int value) { return value % 2 == 0; }) ``` Validation is explicit: ```cpp 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: ```cpp auto temperature = device.read<&Device::temperature>(); device.write<&Device::temperature>(30.0); ``` Compile-time key access is also available: ```cpp 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. ```cpp template concept Can_Write_Serial = requires(Object& object) { object.template write<&Device::serial_number>(1); }; static_assert(!Can_Write_Serial); ``` ## 13. Read-only fast path Stored read-only properties are statically removed from managed locking. Given: ```cpp field<&Device::serial_number>(key<"serial_number">, read_only) ``` Structive resolves: ```text 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 | ```cpp 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: ```cpp 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: ```cpp 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 ```cpp 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: ```cpp Device device{ property_synchronization( synchronization(sync_all_shared) ) }; ``` For typed member rules: ```cpp Device device{ property_synchronization( 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 ```cpp auto view = device.resolved_synchronization(); auto count = view.lock_count; ``` Inspect a member slot: ```cpp auto slot = device.lock_slot<&Device::temperature>(); ``` No-lock properties use: ```cpp 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: ```cpp auto guard = device.lock_shared<&Device::temperature, &Device::pressure>(); auto by_member = guard.get<&Device::temperature>(); auto by_key = guard.get<"pressure">(); ``` Write guard: ```cpp 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 ```cpp 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: ```cpp schema.for_each_property([&](auto index, const auto& descriptor) { }); ``` Readable value traversal: ```cpp device.for_each_readable([&](auto index, const auto& descriptor, const auto& value) { }); ``` Locked readable traversal: ```cpp 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: ```cpp 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: ```cpp computed_property([](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: ```cpp 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: ```cpp trusted_computed_property<&Device::value>(key<"value">) ``` Trusted getter/setter: ```cpp 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`. ```cpp Property_Object_Base& erased = device; ``` Introspection: ```cpp erased.runtime_object_type(); erased.runtime_property_count(); ``` ### 22.1 Runtime read ```cpp 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 ```cpp 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: ```cpp Property_Object ``` No-lock: ```cpp Property_Object ``` `No_Lock_Policy` stores no real mutex array and avoids real lock objects on managed hot paths. ## 24. Raw object access ```cpp Device& raw = device.unsafe_object(); ``` or normal public member access: ```cpp 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.