Struct ParameterServer 

pub struct ParameterServer<'s> { /* private fields */ }

Parameter server over caller-owned storage

Stores parameters in a ParameterTable the caller lends it; the table’s length is the capacity. ParameterStorage is the usual way to produce one, defaulting to the build-time MAX_PARAMETERS slots.

Keyed by node — phase-426 W1

Every per-parameter method takes a NodeKey first. The slot arena is shared (one table per executor), but a name is only ever looked up within one node, so two nodes composed onto one executor (RFC-0047) hold independent values for the same name — which is what upstream does, where each node owns a table and a set of six services.

Example

use nros_params::{NodeKey, ParameterServer, ParameterStorage, ParameterValue};

let mut storage = ParameterStorage::<8>::new();
let mut server = ParameterServer::new_in(storage.as_table());
let talker = NodeKey::new(0);
let listener = NodeKey::new(1);

// Declare a parameter with initial value
server.declare(talker, "rate", ParameterValue::Double(1.0));
server.declare(listener, "rate", ParameterValue::Double(2.0));

// Get parameter value
assert_eq!(
    server.get(talker, "rate").and_then(|v| v.as_double()),
    Some(1.0)
);
assert_eq!(
    server.get(listener, "rate").and_then(|v| v.as_double()),
    Some(2.0)
);

// Set parameter value
server.set(talker, "rate", ParameterValue::Double(3.0));

Implementations

impl<'s> ParameterServer<'s>

pub fn take_truncated_descriptions( &mut self, report: impl FnMut(NodeKey, &str), ) -> usize

phase-446 F2 – report each declared parameter whose description was truncated to NROS_MAX_PARAM_DESCRIPTION_LEN, ONCE, and forget it.

This crate has no logger, so it records the truncation on the descriptor and the executor, which has one, drains it here and logs. The truncation itself happens where the text is given (ParameterDescriptor::set_description), and a declaration can come through several builders; the store is where every one of them lands. Returns how many were reported.

pub fn new_in(table: ParameterTable<'s>) -> ParameterServer<'s>

Create a parameter server over table.

The server ADOPTS whatever the table already holds: count is recovered from the occupied slots rather than assumed zero. That is what makes a table safe to hand to a second server after the first is dropped (and what lets storage arrive pre-seeded), where assuming empty would desynchronise the count from the slots — is_full wrong in one direction, remove underflowing in the other. Fresh ParameterStorage is all-None, so the usual path costs one scan and starts at zero.

pub fn set_allow_undeclared(&mut self, node: NodeKey, allow: bool)

Let a wire-facing set (apply) create a parameter node never declared. Default false: a remote set on a misspelled name used to report success and create the misspelling (issue 1151); now it is refused with a reason unless this is switched on, as upstream.

phase-426 W1 — scoped to node. Switching it on for /talker leaves /listener refusing undeclared names.

pub fn allows_undeclared(&self, node: NodeKey) -> bool

Whether apply may declare an unknown name on node.

pub fn set_parameter_events(&mut self, node: NodeKey, on: bool)

phase-491 W3 — log node’s changes for /parameter_events (rclc’s notify_changed_over_dds). Off by default, so a node nobody asked events for pays nothing.

pub fn pop_parameter_event(&mut self) -> Option<PendingParameterEvent>

phase-491 W3 — the oldest change waiting for /parameter_events.

pub fn take_parameter_events_dropped(&mut self) -> u32

phase-491 W3 — how many changes found the log full since the last call, and reset the count.

pub fn set_delete_on_not_set(&mut self, node: NodeKey, on: bool)

phase-491 W2 — make a wire-facing NOT_SET on node DELETE the parameter, after the on-set hooks accept (old, None). This is rclc’s parameter server (rclc_parameter_server_set_service_callback); the default, off, keeps rclcpp’s refusal.

pub fn len(&self, node: NodeKey) -> usize

Get the number of parameters node has stored.

pub fn is_empty(&self, node: NodeKey) -> bool

Check if node has no parameters

pub fn total_len(&self) -> usize

Parameters held across EVERY node — how much of the shared arena is in use. len is the per-node question; this one is the capacity question’s other half.

pub fn capacity(&self) -> usize

Capacity of the borrowed table.

phase-382 W2’ — this is the TABLE’s length, not MAX_PARAMETERS. The build-time knob only picks the default size of a ParameterStorage.

phase-426 W1 — the arena is SHARED across nodes, so this is not a per-node budget: MAX_PARAMETERS bounds the image, not each node.

pub fn is_full(&self) -> bool

Check if the server is at capacity (across every node)

pub fn declare( &mut self, node: NodeKey, name: &str, value: ParameterValue, ) -> bool

Declare a new parameter with a value on node

If the parameter already exists, this does nothing and returns false. Returns true if the parameter was declared successfully.

phase-428 W6 remainder: this is the method Executor::declare_parameter delegates to, so marking only the wrapper would leave the class half fixed one crate down.

pub fn declare_with_descriptor( &mut self, node: NodeKey, name: &str, value: ParameterValue, descriptor: Option<ParameterDescriptor>, ) -> bool

Declare a new parameter with value and descriptor on node

The descriptor provides metadata like description, constraints, and read-only flag.

phase-428 W6 remainder: see Self::declare. Every false arm below is a REFUSAL (name taken, table full, value rejected), never a question.

pub fn try_declare( &mut self, node: NodeKey, name: &str, value: ParameterValue, ) -> Result<(), DeclarationError>

declare, saying WHY it refused — phase-417 W4.a.

rclrs separates declare-time failures from set-time ones (DeclarationError against SetParameterResult); ours returned a bare bool for “the name was taken”, “the table was full” and “the default is outside the range” alike, so a caller could not tell a programming error from a capacity one. The bool spellings above forward to this, so there is exactly one declare path.

pub fn try_declare_with_descriptor( &mut self, node: NodeKey, name: &str, value: ParameterValue, descriptor: Option<ParameterDescriptor>, ) -> Result<(), DeclarationError>

declare_with_descriptor, saying WHY it refused. See try_declare.

pub fn check_apply( &self, node: NodeKey, name: &str, value: &ParameterValue, ) -> SetParameterResult

Dry-run of apply: the verdict a wire-facing set would get, without changing anything. SetParametersAtomically runs this over the whole batch before applying any of it.

pub fn apply( &mut self, node: NodeKey, name: &str, value: ParameterValue, ) -> SetParameterResult

THE wire-facing set — what one element of SetParameters / SetParametersAtomically does (issue 1151).

An existing parameter is set through set. An unknown name is Undeclared unless set_allow_undeclared was switched on FOR THAT NODE, in which case it is declared (or StorageFull). Every service handler and every facade writer goes through here so the by-value oracle, the streaming path, the atomic pre-check and the C setters cannot disagree about what “undeclared” means.

pub fn apply_staged( &mut self, node: NodeKey, name: &str, staged: &mut ParameterValue, ) -> SetParameterResult

apply, taking the value from a caller-owned STAGING slot instead of by value — RFC-0105 D10.2 / issue 1812.

A ParameterValue is sized by its largest variant (~8.5 KiB at the default bounds), so apply(value) puts one on the caller’s stack, and the wire handler that decoded it put another there before that. A remote set decodes into a slot carved from the executor backing and hands it here: the same rules, hooks and order as apply, and the write is a SWAP between the slot and the stored value, so no value-sized temporary exists on any path that sets an existing parameter. On return staged holds the previous value (or whatever it held, when the set was refused); its content is scratch.

The one path that still builds an entry is the undeclared add (allow_undeclared), which places an EMPTY entry first and then swaps the value into it; see declare_placeholder.

pub fn set_local( &mut self, node: NodeKey, name: &str, value: ParameterValue, ) -> SetParameterResult

phase-491 W2 (RFC-0105 D6/D7) — rclc’s LOCAL typed set, rclc_parameter_set_{bool,int,double}.

rclc’s owner of a parameter is not bound by its own read-only flag or range: read-only is “read-only to the OUTSIDE”, and rclc never checks a range at all. So this is type, then the hooks with (old, new), then the write — and nothing else. Remote writes keep going through apply, which enforces both.

The type check compares against the STORED value’s type unless the descriptor allows dynamic typing, because rclc refuses a typed set of the wrong type (RCLC_PARAMETER_TYPE_MISMATCH) whether or not a descriptor was ever attached.

pub fn add_on_set_parameters_callback( &mut self, node: NodeKey, callback: fn(NodeKey, &str, Option<&ParameterValue>, Option<&ParameterValue>, OnSetContext) -> bool, ctx: OnSetContext, ) -> Option<OnSetParameterHandle>

Register an accept/reject hook for writes to node — rclcpp’s add_on_set_parameters_callback (phase-417 W4.a).

The callback runs on every apply: a remote ros2 param set, a C++ Node::set_parameter, a Rust Executor::set_parameter. Returning false refuses the write with SetParameterResult::Rejected and leaves the stored value alone.

None when all MAX_ON_SET_CALLBACKS slots are taken — a refusal, never a silent eviction.

pub fn remove_on_set_parameters_callback( &mut self, handle: OnSetParameterHandle, ) -> bool

Unregister a hook — rclcpp’s remove_on_set_parameters_callback. false if the slot was already empty.

pub fn on_set_callbacks_free(&self) -> usize

How many hook slots are free. Lets a caller ask before registering rather than discovering the bound as a None.

pub fn set_parameter_description( &mut self, node: NodeKey, name: &str, description: &str, additional_constraints: &str, ) -> bool

Attach a description and free-text constraints to a declared parameter — rclc’s rclc_add_parameter_description. Either text may be empty. false if the parameter is not declared on node.

pub fn set_parameter_read_only( &mut self, node: NodeKey, name: &str, read_only: bool, ) -> bool

Mark a declared parameter read-only, so every later write is SetParameterResult::ReadOnly — rclc’s rclc_set_parameter_read_only. false if not declared on node.

pub fn set_parameter_integer_range( &mut self, node: NodeKey, name: &str, min: i64, max: i64, step: i64, ) -> bool

Attach an integer range to a declared parameter — rclc’s rclc_add_parameter_constraint_integer.

Refuses an ill-formed range, and refuses one the CURRENT value does not satisfy: attaching a constraint that the stored value already violates would leave the store in a state no set could have produced, and ros2 param describe would then advertise a bound the value breaks.

pub fn set_parameter_float_range( &mut self, node: NodeKey, name: &str, min: f64, max: f64, step: f64, ) -> bool

Attach a floating-point range to a declared parameter — rclc’s rclc_add_parameter_constraint_double. See set_parameter_integer_range.

pub fn apply_atomically<'x, I>( &mut self, node: NodeKey, items: I, ) -> SetParameterResult

where I: Iterator<Item = Option<(&'x str, ParameterValue)>> + Clone,

All-or-nothing multi-set — ~/set_parameters_atomically’s local twin (phase-417 W4.a).

We SERVED this and offered it in no language, so the only way to reach our own atomic set was over the wire. This is the same two passes the service handler makes: every item is checked against the CURRENT state, and only if all pass is any applied.

items yields None for an element that could not even be turned into a value — which is how the service handler reports a wire value that does not fit the store’s capacity (issue 0323) — and a None refuses the batch like any other failing check.

It is Clone because the two passes walk it twice; a slice iterator is.

Returns SetParameterResult::Success, or the FIRST verdict that refused. Nothing is written on a refusal.

The per-item check is against the state BEFORE the batch, not against the state each earlier item would leave. That is the service handler’s contract verbatim, and it matters in one case: a batch that declares more undeclared names than there are free slots passes the check and fills what it can. Making the pre-check cumulative would need a speculative copy of the table, which is the allocation this store does not have.

pub fn get(&self, node: NodeKey, name: &str) -> Option<&ParameterValue>

Get a parameter value by name

pub fn get_parameter(&self, node: NodeKey, name: &str) -> Option<&Parameter>

Get a parameter by name

pub fn get_descriptor( &self, node: NodeKey, name: &str, ) -> Option<&ParameterDescriptor>

Get a parameter descriptor by name

pub fn set( &mut self, node: NodeKey, name: &str, value: ParameterValue, ) -> SetParameterResult

Set a parameter value

Returns the result of the set operation.

pub fn unset(&mut self, node: NodeKey, name: &str) -> SetParameterResult

Unset an optional parameter (set to NotSet)

This bypasses the type check to allow optional parameters to be unset. Returns an error if the parameter is read-only.

pub fn set_or_declare( &mut self, node: NodeKey, name: &str, value: ParameterValue, ) -> SetParameterResult

Set or declare a parameter — an EXPLICIT auto-declare for in-image callers.

If the parameter exists, sets its value. Otherwise, declares it. This ignores allow_undeclared on purpose: the flag governs what a REMOTE set may do; a Rust caller naming this method has opted in by naming it. Nothing on the wire path — and, since phase-426 W2, nothing on the C or C++ facade path either — reaches here (issue 1151).

pub fn has(&self, node: NodeKey, name: &str) -> bool

Check if a parameter exists

pub fn remove(&mut self, node: NodeKey, name: &str) -> bool

Remove a parameter

Returns true if the parameter was removed.

pub fn get_type(&self, node: NodeKey, name: &str) -> Option<ParameterType>

Get the type of a parameter

pub fn iter(&self, node: NodeKey) -> impl Iterator<Item = &Parameter>

Iterate over node’s parameters

pub fn list_names(&self, node: NodeKey) -> impl Iterator<Item = &str>

List node’s parameter names

pub fn list_with_prefix<'a>( &'a self, node: NodeKey, prefix: &'a str, ) -> impl Iterator<Item = &'a str>

List node’s parameter names with a given prefix

pub fn get_bool(&self, node: NodeKey, name: &str) -> Option<bool>

Get a bool parameter value

pub fn get_integer(&self, node: NodeKey, name: &str) -> Option<i64>

Get an integer parameter value

pub fn get_double(&self, node: NodeKey, name: &str) -> Option<f64>

Get a double parameter value

pub fn get_string(&self, node: NodeKey, name: &str) -> Option<&str>

Get a string parameter value

pub fn set_bool( &mut self, node: NodeKey, name: &str, value: bool, ) -> SetParameterResult

Set a bool parameter value

pub fn set_integer( &mut self, node: NodeKey, name: &str, value: i64, ) -> SetParameterResult

Set an integer parameter value

pub fn set_double( &mut self, node: NodeKey, name: &str, value: f64, ) -> SetParameterResult

Set a double parameter value

pub fn set_string( &mut self, node: NodeKey, name: &str, value: &str, ) -> SetParameterResult

Set a string parameter value

pub fn declare_parameter( &mut self, node: NodeKey, descriptor: ParameterDescriptor, initial_value: Option<&ParameterValue>, ) -> Result<(), SetParameterResult>

Declare a parameter with a descriptor and optional initial value.

This is a more comprehensive declaration method used by the typed parameter API.

Arguments

• node: The node the parameter belongs to.
• descriptor: The metadata for the parameter.
• initial_value: An optional initial value for the parameter. If None, the parameter will be initialized to ParameterValue::NotSet.

pub fn get_parameter_value( &self, node: NodeKey, name: &str, ) -> Option<ParameterValue>

Get the current value of a parameter.

Returns Some(ParameterValue) if the parameter exists, None otherwise. The ParameterValue is cloned to avoid lifetime issues with &mut self.

pub fn set_parameter_value( &mut self, node: NodeKey, name: &str, value: ParameterValue, ) -> SetParameterResult

Set the value of a parameter.

Returns SetParameterResult::Success on success, or an error if the parameter is read-only, type mismatches, or is out of range.