Module attrs 

Attribute dictionary for type-safe, heterogeneous key-value storage with serde support.

This module provides Attrs, a type-safe dictionary that can store heterogeneous values and serialize/deserialize them using serde. All stored values must implement AttrValue to ensure the entire dictionary can be serialized.

Keys are automatically registered at compile time using the declare_attrs! macro and the inventory crate, eliminating the need for manual registry management.

Basic Usage

use std::time::Duration;

use hyperactor_config::attrs::Attrs;
use hyperactor_config::attrs::declare_attrs;

// Declare keys with their associated types
declare_attrs! {
   /// Request timeout
   attr TIMEOUT: Duration;

  /// Maximum retry count
  attr MAX_RETRIES: u32 = 3;  // with default value
}

let mut attrs = Attrs::new();
attrs.set(TIMEOUT, Duration::from_secs(30));

assert_eq!(attrs.get(TIMEOUT), Some(&Duration::from_secs(30)));
assert_eq!(attrs.get(MAX_RETRIES), Some(&3));

Serialization

Attrs can be serialized to and deserialized automatically:

use std::time::Duration;

use hyperactor_config::attrs::Attrs;
use hyperactor_config::attrs::declare_attrs;

declare_attrs! {
  /// Request timeout
  pub attr TIMEOUT: Duration;
}

let mut attrs = Attrs::new();
attrs.set(TIMEOUT, Duration::from_secs(30));

// Serialize to JSON
let json = serde_json::to_string(&attrs).unwrap();

// Deserialize from JSON (no manual registry needed!)
let deserialized: Attrs = serde_json::from_str(&json).unwrap();

assert_eq!(deserialized.get(TIMEOUT), Some(&Duration::from_secs(30)));

Meta attributes

An attribute can be assigned a set of attribute values, associated with the attribute key. These are specified by @-annotations in the declare_attrs! macro:

use std::time::Duration;

use hyperactor_config::attrs::Attrs;
use hyperactor_config::attrs::declare_attrs;

declare_attrs! {
  /// Is experimental?
  pub attr EXPERIMENTAL: bool;

  /// Request timeout
  @meta(EXPERIMENTAL = true)
  pub attr TIMEOUT: Duration;
}

assert!(TIMEOUT.attrs().get(EXPERIMENTAL).unwrap());

Meta attributes can be used to provide more generic functionality on top of the basic attributes. For example, a library can use meta-attributes to specify the behavior of an attribute.

Macros

declare_attrs

Declares attribute keys using a lazy_static! style syntax.

Structs

Attrs

A heterogeneous, strongly-typed attribute dictionary with serialization support.

Key

A typed key for the attribute dictionary.

Statics

OPERATION_CONTEXT_HEADER

Meta-attribute marker for operation context carried on envelope headers. Attrs declared with @meta(OPERATION_CONTEXT_HEADER = true) are stamped onto outgoing request envelopes and copied onto reply envelopes by the marker-driven helpers (stamp_marked_attrs_into_flattrs, copy_marked_flattrs).

Traits

AttrValue

This trait must be implemented by all attribute values. In addition to enforcing the supertrait Named + Sized + Serialize + DeserializeOwned + Send + Sync + Clone, AttrValue requires that the type be representable in “display” format.

ErasedKey

A trait for type-erased keys.

Functions

copy_marked_flattrs

Copy every entry from src to dst whose declared attribute key carries the bool meta marker marker with value true. Overwrite semantics (see Flattrs::set_serialized). Entries whose declared key lacks the marker — or whose key_hash does not resolve to a declared key in the current binary’s inventory — are silently skipped.

fnv1a_hash

Compute FNV-1a hash of a byte slice (const-compatible).

is_attr_marked_with

Returns Some(true) when the declared attribute key with this name carries the given bool meta marker with value true, Some(false) when it carries the marker with value false, and None for unknown names or declared keys that do not carry the marker at all.

lookup_key_info

Look up a key info by its hash using the global registry.

lookup_key_info_by_name

Look up a key info by name using the global registry.

marked_attr_names

Returns the set of all declared attribute key names that carry the given bool meta marker (set to true) in the attrs inventory linked into the current binary.

stamp_marked_attrs_into_flattrs

Copy every entry from attrs onto dst whose declared attribute key carries the bool meta marker marker with value true. Overwrite semantics (see Flattrs::set_serialized) — a later write for the same key_hash is the value returned by Flattrs::get. Entries whose declared key lacks the marker are silently skipped; entries whose key is not declared are also silently skipped.