From bf51e44b7bf61ecbd274d6908804e553a3a8c3f4 Mon Sep 17 00:00:00 2001 From: Jure Varlec Date: Thu, 26 Feb 2026 12:24:58 +0000 Subject: [PATCH] doc: explain type requirements for post() Currently, the user learns that `SharedPV::post()` requires the posted value to be created from the same type instance as the value given to `SharedPV::open()` only when they try to do it differently and are presented with an error message. This is an attempt to document this requirement. --- example/ticker.cpp | 7 +++++++ src/pvxs/sharedpv.h | 8 +++++++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/example/ticker.cpp b/example/ticker.cpp index 3e8f6f8..582fdf3 100644 --- a/example/ticker.cpp +++ b/example/ticker.cpp @@ -100,6 +100,13 @@ int main(int argc, char* argv[]) uint32_t count = 0u; while(!done.wait(delay)) { + // The value that will be given to post() must come from the same type + // _instance_ as the initial value used when calling open(). In other + // words, doing + // auto val = nt::NTScalar{TypeCode::UInt32}.create(); + // won't work because it creates a different NTScalar instance. Either + // keep reusing the same Value, clone the existing Value, or keep aroud + // the type instance and create values from there. auto val = initial.cloneEmpty(); val["value"] = count++; diff --git a/src/pvxs/sharedpv.h b/src/pvxs/sharedpv.h index 95e69a7..416efd3 100644 --- a/src/pvxs/sharedpv.h +++ b/src/pvxs/sharedpv.h @@ -71,8 +71,14 @@ struct PVXS_API SharedPV //! Reverse the effects of open() and force disconnect any remaining clients. void close(); - //! Update the internal data value, and dispatch subscription updates to any clients. + /** Update the internal data value, and dispatch subscription updates to any clients. + * + * The value given as the argument must be created from the same `TypeDef` + * instance as the value given to `SharedPV::open()`. It is recommended that + * the same value (or its clone) is reused. + */ void post(const Value& val); + //! query the internal data value and update the provided Value. void fetch(Value& val) const; //! Return a (shallow) copy of the internal data value