Expand description
Canonical imports for Copper applications.
This module intentionally re-exports each stable application-facing group once. Runtime internals, remote-debug plumbing, and experimental executor APIs should be imported from their explicit module paths instead of from the prelude.
Re-exports§
pub use crate::units;pub use ctrlc;
Modules§
- app
- bevy_
reflect - Runtime reflection helpers built on top of
bevy_reflect. - memmap
- This is the memory map file implementation for the unified logger for Copper. It is std only.
- noop
- reflect_
serde - Serde integration for reflected types.
Macros§
- __
cu29_ defmt_ debug - __
cu29_ defmt_ error - __
cu29_ defmt_ info - __
cu29_ defmt_ warn - bundle_
resources - critical
- Log a critical message as a Copper structured log entry.
- debug
- Log a debug message as a Copper structured log entry.
- defmt_
debug - defmt_
error - defmt_
info - defmt_
warn - error
- Log an error message as a Copper structured log entry.
- gen_
cumsgs - Generates the CopperList content type from a config. gen_cumsgs!(“path/to/config.toml”) It will create a new type called CuStampedDataSet you can pass to the log reader for decoding:
- info
- Log an info message as a Copper structured log entry.
- input_
msg - intern
- Interns a string For example:
- output_
msg - resources
- rx_
channels - Declares the receive channels of a
CuBridgeimplementation. - safety_
check - safety_
check_ eq - tx_
channels - Declares the transmit channels of a
CuBridgeimplementation. - warning
- Log a warning message as a Copper structured log entry.
Structs§
- Aligned
Buffer - A buffer that is aligned to a specific size with the Element of type E.
- Bincode
Adapter - Bincode Adapter for Freezable tasks This allows the use of the bincode API directly to freeze and thaw tasks.
- Borrowed
- Wrapper used when a task needs to borrow a resource that remains managed by
the
ResourceManager. - Bridge
Channel - Bridge
Channel Config - Runtime descriptor that includes the parsed per-channel configuration.
- Bridge
Channel Descriptor - Static metadata describing a channel. Used to pass configuration data at runtime without leaking the channel’s payload type.
- Bridge
Config - Declarative definition of a bridge component with a list of channels.
- Bundle
Context - Context passed to bundle providers when building resources.
- Bundle
Index - Index identifying a resource bundle in the active mission.
- Clock
Debug Scalar Registration - Cnx
- This represents a connection between 2 tasks (nodes) in the configuration graph.
- Component
Config - This is the configuration of a component (like a task config or a monitoring config):w It is a map of key-value pairs. It is given to the new method of the task implementation.
- Component
Id - Strongly-typed index into
CuMonitoringMetadata::components. - Config
Error - Copper
Lisk Mask - Not implemented yet. This mask will be used to for example filter out necessary regions of a copper list between remote systems.
- Copper
List - Copper
List Entry - One message entry in CopperList slot order with resolved component identity.
- Copper
List Info - Copper
List IoStats - Reported data about CopperList IO for a single iteration.
- Copper
List Layout - Static monitor-side CopperList indexing layout.
- Copper
List View - Per-loop monitor view over CopperList metadata paired with static component mapping.
- Counting
Alloc - A simple allocator that counts the number of bytes allocated and deallocated.
- CuArray
- Copper friendly wrapper for a fixed size array.
T: Cloneis required because this type derivesReflect, and the reflection path requires the reflected value to be cloneable. - CuArray
Vec - A Copper-friendly wrapper around ArrayVec with bincode serialization support.
- CuCompact
String - CuConfig
- CuConfig is the programmatic representation of the configuration graph. It is a directed graph where nodes are tasks and edges are connections between tasks.
- CuContext
- Execution context passed to task and bridge callbacks.
- CuContext
Builder - Builder for
CuContext. - CuDebug
Session - CuDuration
- For Robot times, the underlying type is a u64 representing nanoseconds. It is always positive to simplify the reasoning on the user side.
- CuDuration
Statistics - A Specialized statistics object for CuDuration. It will also keep track of the jitter between the values.
- CuError
- Common copper Error type.
- CuGraph
- CuHandle
- A shareable handle to a pooled or detached object.
- CuHost
Memory Pool - A pool of host memory buffers.
- CuInstant
- High-precision instant in time, represented as nanoseconds since an arbitrary epoch
- CuList
Slot - Strongly-typed CopperList slot index.
- CuLists
Manager - This structure maintains the entire memory needed by Copper for one loop for the inter tasks communication within a process. P or Payload is typically a Tuple of various types of messages that are exchanged between tasks. N is the maximum number of in flight Copper List the runtime can support.
- CuLog
Entry - This is the basic structure for a log entry in Copper.
- CuLog
Origin - Runtime origin metadata attached to a structured log entry when available.
- CuMonitoring
Metadata - Immutable runtime-provided metadata passed once to
CuMonitor::new. - CuMonitoring
Runtime - Runtime-provided dynamic monitoring handles passed once to
CuMonitor::new. - CuMsg
IoCache - CuMsg
IoCapture Guard - CuMsg
IoStats - CuMsg
Metadata - CuMsgMetadata is a structure that contains metadata common to all CuStampedDataSet.
- CuMsg
Origin - Origin metadata captured when a Copper-aware transport receives a remote message.
- CuNo
Bridge Channels - Empty channel set used when a simulated bridge has no channel on one side.
- CuRuntime
- This is the main structure that will be injected as a member of the Application struct. CT is the tuple of all the tasks in order of execution. CL is the type of the copper list, representing the input/output messages for all the tasks.
- CuShared
Memory Buffer - CuShared
Memory Handle Descriptor - CuShared
Memory Pool - A pool of fixed-size shared-memory buffers that can be leased to a child process without copying the underlying bytes.
- CuSim
Bridge - Placeholder bridge used in simulation when a bridge is configured with
run_in_sim: false. - CuSim
Sink Task - This is a placeholder task for a sink task for the simulations. It basically does nothing in place of a real driver so it won’t try to initialize any hardware.
- CuSim
SrcTask - This is a placeholder task for a source task for the simulations. It basically does nothing in place of a real driver so it won’t try to initialize any hardware.
- CuStamped
Data - CuMsg is the envelope holding the msg payload and the metadata between tasks.
- CuTime
- A robot time is a monotonic timestamp in nanoseconds from the robot clock epoch.
- CuTime
Range - Represents a time range.
- Debug
Field Descriptor - Debug
Scalar Registration - EndOf
LogMarker - Payload stored in the end-of-log section to signal whether the log was cleanly closed.
- Execution
Marker - Execution progress marker emitted by the runtime before running a component step.
- Includes
Config - Includes are used to include other configuration files.
- Instance
Config SetOperation - One path-based config overlay applied to a parsed local Copper config.
- Jump
Outcome - Result of a jump/step, useful for benchmarking cache effectiveness.
- KeyFrame
- A KeyFrame is recording a snapshot of the tasks state before a given copperlist. It is a double encapsulation: this one recording the culistid and another even in bincode in the serialized_tasks.
- Live
Statistics - Accumulative stat object that can give your some real time statistics. Uses a fixed-size bucketed histogram for accurate percentile calculations.
- LogPosition
- Absolute position inside a unified log (slab index + byte offset).
- LogStream
- A wrapper around the unifiedlogger that implements the Write trait.
- Logger
Runtime - The lifetime of this struct is the lifetime of the logger.
- Logging
Codec Spec - Logging
Config - Main
Header - The main file header of the datalogger.
- Missions
Config - Missions are used to generate alternative DAGs within the same configuration.
- Monitor
Component Metadata - Static identity entry for one monitored runtime component.
- Monitor
Config - Monitor
Connection - Monitor
Execution Probe - Platform-neutral monitor view of runtime execution progress.
- Monitor
Node - Monitor
Topology - Multi
Copper Config - Strict umbrella configuration describing multiple Copper subsystems and their explicit links.
- Multi
Copper Endpoint - Typed endpoint reference used by validated multi-Copper interconnects.
- Multi
Copper Interconnect - Validated explicit interconnect between two subsystem endpoints.
- Multi
Copper Interconnect Config - One explicit interconnect between two subsystem bridge channels.
- Multi
Copper Subsystem - Validated subsystem entry with its compiler-assigned numeric subsystem code and parsed local Copper config.
- Multi
Copper Subsystem Config - One subsystem participating in a multi-Copper deployment.
- NoMonitor
- A do nothing monitor if no monitor is provided. This is basically defining the default behavior of Copper in case of error.
- Node
- A node in the configuration graph. A node represents a Task in the system Graph.
- Node
Logging - Configuration for logging in the node.
- Noop
Logger - Noop
Section Storage - NullLog
- Observed
Writer - A bincode writer wrapper that reports every encoded byte to Copper’s observation counters.
- Option
CuTime - Homebrewed
Option<CuDuration>to avoid using 128bits just to represent an Option. - Owned
- Lightweight wrapper used when a task needs to take ownership of a resource.
- Owning
IoWriter - Panic
Hook Registration - Panic
Report - Partial
CuTime Range - Represents a time range with possible undefined start or end or both.
- Payload
IoStats - Reflect
Serializer - A general purpose serializer for reflected types.
- Resource
Binding Map - Static mapping between user-defined binding ids and resource keys.
- Resource
Bundle Config - Declarative definition of a resource bundle.
- Resource
Key - Typed identifier for a resource entry.
- Resource
Manager - Manages the concrete resources available to tasks and bridges.
- Robot
Clock - A running Robot clock. The clock is a monotonic clock that starts at an arbitrary reference time. It is clone resilient, ie a clone will be the same clock, even when mocked.
- Robot
Clock Mock - A mock clock that can be controlled by the user.
- Runtime
Config - Runtime
Execution Probe - Lock-free runtime-side progress probe.
- Runtime
Lifecycle Record - One event record persisted in the
UnifiedLogType::RuntimeLifecyclesection. - Runtime
Lifecycle Stack Info - Stack and process identification metadata persisted in the runtime lifecycle log.
- Section
Cache Stats - Section-cache statistics for a debug session.
- Section
Handle - A SectionHandle is a handle to a section in the datalogger. It allows tracking the lifecycle of the section.
- Section
Header - Each concurrent sublogger is tracked through a section header. They form a linked list of sections. The entry type is used to identify the type of data in the section.
- Serialization
Data - Contains data relevant to the automatic reflect powered (de)serialization of a type.
- Shared
Handle Serialization Guard - Simple
File Writer - This allows this crate to be used outside of Copper (ie. decoupling it from the unifiedlog.
- Subsystem
- Compile-time subsystem identity embedded in generated Copper applications.
- Task
Output Spec - Trait to trace back from the CopperList the origin of each message slot.
- Thread
Pool Bundle - Type
Registry - A registry of reflected types.
- Typed
Reflect Serializer - A serializer for reflected types whose type will be known during deserialization.
- Unified
LogStatus - Basic statistics for the unified logger. Note: the total_allocated_space might grow for the std implementation
- Unified
Logger Builder - Use this builder to create a new DataLogger.
- Unified
LoggerIO Reader - This a convenience wrapper around the UnifiedLoggerRead to implement the Read trait.
- Unified
Logger Read - A read side of the memory map based unified logger.
- Unified
Logger Write - A write side of the datalogger.
Enums§
- Allocated
Section - Bridge
Channel Config Representation - Directional mapping for bridge channels.
- Clock
Debug Scalar Kind - Component
Type - Runtime component category used by monitoring metadata and topology.
- Config
Graphs - Copper
List State - Those are the possible states along the lifetime of a CopperList.
- CuBridge
Lifecycle State - Lifecycle callbacks for bridges when running in simulation.
- CuComponent
State - Lifecycle state of a monitored component.
- CuDirection
- A simple wrapper enum for
petgraph::Direction, designed to be converted into it via theFromtrait. - CuHandle
Inner - A handle to a pooled or detached object.
- CuLatched
State - Consumer-side cache updated by
CuLatchedStateUpdate. - CuLatched
State Update - Producer-side update for a stateful value cached by downstream consumers.
- CuLog
Level - Log levels for Copper.
- CuNo
Bridge Channel Id - Empty channel-id enum used when a simulated bridge has no channel on one side.
- CuShared
Memory Element Type - CuTask
Callback State - This is the state that will be passed to the simulation support to hook into the lifecycle of the tasks.
- Debug
Field Kind - Debug
Field Semantics - Decision
- Monitor decision to be taken when a component step errored out.
- Flavor
- Distinguishes regular tasks from bridge nodes so downstream stages can apply bridge-specific instantiation rules.
- Runtime
Lifecycle Config Source - Identifies where the effective runtime configuration came from.
- Runtime
Lifecycle Event - Runtime lifecycle events emitted in the dedicated lifecycle section.
- SimOverride
- This is the answer the simulator can give to control the simulation flow.
- Task
Kind - Declares which Copper task trait a task node implements.
- Thread
Pool Id - Tov
- The time of validity of a message can be more than one time but can be a time range of Tovs. For example a sub scan for a lidar, a set of images etc… can have a range of validity.
- TxEmpty
Policy - Compile-time description of a single bridge channel, including the message type carried on it.
- Type
Info - Compile-time type information for various reflected types.
- Unified
LogType - Defines the types of what can be logged in the unified logger.
- Unified
Logger - Holds the read or write side of the datalogger.
- Value
Constants§
- ANONYMOUS
- COMPACT_
STRING_ CAPACITY - DEFAULT_
KEYFRAME_ INTERVAL - DEFAULT_
MISSION_ ID - MAIN_
MAGIC - ID to spot the beginning of a Copper Log
- MAX_
LOG_ PARAMS_ ON_ STACK - MAX_
RATE_ TARGET_ HZ - Maximum representable Copper runtime rate target in whole Hertz.
- NC_
ENDPOINT - Special destination endpoint used to mark an output as intentionally not connected.
- SECTION_
HEADER_ COMPACT_ SIZE - SECTION_
MAGIC - ID to spot a section of Copper Log
- UNIFIED_
LOG_ FORMAT_ VERSION - Version of the unified log file format.
Traits§
- Array
Like - Bridge
Channel Info - Type-erased metadata exposed for channel enumeration and configuration.
- Bridge
Channel Set - Describes a set of channels for one direction (Tx or Rx) of the bridge.
- Clock
Provider - A trait to provide a clock to the runtime.
- Copper
List Tuple - A CopperListTuple needs to be encodable, decodable and fixed size in memory.
- CuApplication
- A trait that defines the structure and behavior of a CuApplication.
- CuBridge
- Public trait implemented by every copper bridge.
- CuDistributed
Replay Application - Simulation-enabled applications that can be instantiated for distributed replay.
- CuList
Zeroed Init - Initializes fields that cannot be zeroed after allocating a zeroed
CopperList. - CuMonitor
- Runtime monitoring contract implemented by monitor components.
- CuMsg
Metadata Trait - Key metadata piece attached to every message in Copper.
- CuMsg
Pack - CuMsg
Payload - The state of a task.
- CuPayload
RawBytes - Provides per-output raw payload sizes aligned with
ErasedCuStampedDataSet::cumsgsorder. - CuPool
- A CuPool is a pool of buffers that can be shared between different parts of the code. Handles can be stored locally in the tasks and shared between them.
- CuRecorded
Replay Application - Simulation-enabled applications that can replay a recorded CopperList verbatim.
- CuSim
Application - A trait that defines the structure and behavior of a simulation-enabled CuApplication.
- CuSim
Sink Input - Helper to map a payload type (or tuple of payload types) to the corresponding
input_msg!form. - CuSingle
Output Msg - Helper trait used by codegen when Copper needs to treat a task output as a single message slot without relying on config-declared output edges.
- CuSink
Task - A Sink Task is a task that only consumes messages. For example drivers for actuators are Sink Tasks.
- CuSrc
Task - A Src Task is a task that only produces messages. For example drivers for sensors are Src Tasks. They are in push mode from the runtime. To set the frequency of the pulls and align them to any hw, see the runtime configuration. Note: A source has the privilege to have a clock passed to it vs a frozen clock.
- CuStd
Application - Convenience trait for CuApplication when it is just a std App
- CuSubsystem
Metadata - Compile-time subsystem identity embedded in generated Copper applications.
- CuTask
- This is the most generic Task of copper. It is a “transform” task deriving an output from an input.
- Current
Runtime Copper List - Optional introspection hook exposing the latest runtime-generated CopperList snapshot.
- Debug
Scalar Type - Device
CuPool - A device memory pool can copy data from a device to a host memory pool on top.
- Element
Type - Basic Type that can be used in a buffer in a CuPool.
- Erased
CuStamped Data - A generic trait to expose the generated CuStampedDataSet from the task graph.
- Erased
CuStamped Data Set - Trait to get a vector of type-erased CuStampedDataSet This is used for generic serialization of the copperlists
- Freezable
- The internal state of a task needs to be serializable so the framework can take a snapshot of the task graph.
- GetType
Registration - A trait which allows a type to generate its
TypeRegistrationfor registration into theTypeRegistry. - Matching
Tasks - Metadata
- Represent the minimum set of traits to be usable as Metadata in Copper.
- Named
Resource Bundle Decl - Optional name metadata for resource bundles.
- Payload
Schemas - Trait for providing JSON schemas for CopperList payload types.
- Pool
Monitor - Trait for a Pool to exposed to be monitored by the monitoring API.
- Reflect
Task Introspection - Runtime task-reflect contract exposed by generated Copper applications.
- Reflect
Type Path - Resource
Bindings - Trait implemented by resource binding structs passed to task/bridge
constructors. Implementors pull the concrete resources they need from the
ResourceManager, using the symbolic mapping provided in the Copper config (resources: { name: "bundle.resource" }). - Resource
Bundle - Bundle providers implement this trait to populate the
ResourceManagerwith concrete resources for a given bundle id. - Resource
Bundle Decl - Trait implemented by bundle providers to declare their resource id enum.
- Resource
Id - Trait implemented by resource id enums generated by
bundle_resources!. - Saturating
Sub - Saturating subtraction for time and duration types.
- Section
Storage - A Storage is an append-only structure that can update a header section.
- Type
Path - A static accessor to type paths and names.
- Unified
LogRead - Read back a unified log linearly.
- Unified
LogWrite - The writing interface to the unified logger. Writing is “almost” linear as various streams can allocate sections and track them until they drop them.
- Write
Stream - Defines a basic write, append only stream trait to be able to log or send serializable objects.
Functions§
- abort_
observed_ encode - Aborts any active observed byte counting session.
- begin_
observed_ encode - Starts observed byte counting for the current encode pass.
- build_
monitor_ topology - Derive a monitor-friendly topology from the runtime configuration.
- busy_
wait_ for - A busy looping function based on this clock for a duration. Mainly useful for embedded to spinlocking.
- busy_
wait_ until - A busy looping function based on this until a specific time. Mainly useful for embedded to spinlocking.
- debug_
scalar_ registrations - dump_
type_ registry_ schema - Dumps a stable, human-readable schema snapshot for the registered reflected types.
- enable_
shared_ handle_ serialization - finish_
observed_ encode - Ends observed byte counting and returns the total bytes written.
- format_
logline - Text log line formatter. Only available on std. TODO(gbin): Maybe reconsider that at some point
- format_
message_ only - infer_
task_ kind_ for_ id - initialize
- log
- Public entry point used in release / no-debug paths.
- log_
debug_ mode - This version of log is only compiled in debug mode This allows a normal logging framework to be bridged.
- observed_
encode_ bytes - Returns the number of bytes written so far in the current observed encode pass.
- panic_
payload_ to_ string - payload_
io_ stats - Measures payload bytes using the same encode path Copper uses for logging/export.
- pools_
statistics - Get the list of pools and their statistics. We use SmallVec here to avoid heap allocations while the stack is running.
- read_
configuration - Read a copper configuration from a file.
- read_
configuration_ str - read_
multi_ configuration - Read a strict multi-Copper umbrella configuration from a file.
- read_
multi_ configuration_ str - Read a strict multi-Copper umbrella configuration from a string.
- read_
raw_ counter - rebuild_
logline - Rebuild a log line from the interned strings and the CuLogEntry. This basically translates the world of copper logs to text logs.
- record_
observed_ encode_ bytes - Records bytes written by an observed writer.
- recorded_
copperlist_ timestamp - Returns the earliest recorded
process_time.startfound in a CopperList. - register_
live_ log_ listener - Register a live log listener; subsequent logs invoke
cb. No-op if runtime not initialized. - resolve_
task_ kind_ for_ id - runtime_
panic_ hook_ active - start_
copperlist_ io_ capture - stream_
write - Create a new stream to write to the unifiedlogger.
- structured_
log_ bytes_ total - Returns the total number of bytes written to the structured log stream.
- take_
last_ completed_ handle_ bytes - to_
value - unregister_
live_ log_ listener - Remove any registered live log listener. No-op if runtime not initialized.
- with_
cause - Creates a CuError with a message and cause in a single call.
Type Aliases§
- AscIter
- AscIter
Mut - CuMsg
- This is the robotics message type for Copper with the correct Metadata type that will be used by the runtime.
- CuResult
- Execution
Probe Handle - Instant
- Iter
- IterMut
- Live
LogListener - Callback signature: receives the structured entry plus its format string and param names.
- NodeId
- NodeId is the unique identifier of a node in the configuration graph for petgraph and the code generation.
Attribute Macros§
- copper_
runtime - Adds
#[copper_runtime(config = "path", subsystem = "id", sim_mode = false/true, ignore_resources = false/true)]to your application struct to generate the runtime. if sim_mode is omitted, it is set to false. if ignore_resources is omitted, it is set to false. ifsubsystemis provided,configmust point to a strict multi-Copper config and the selected subsystem local config will be embedded into the generated runtime. This will add a “runtime” field to your struct and implement the “new” and “run” methods. - safety_
case
Derive Macros§
- Deserialize
- Reflect
- The main derive macro used by
bevy_reflectfor deriving itsReflecttrait. - Serialize
- Type
Path - Derives the
TypePathtrait, providing a stable alternative to [std::any::type_name].