Skip to main content Module prelude Copy item path Source pub use crate::units;pub use ctrlc;app bevy_reflect Runtime reflection helpers built on top of bevy_reflect. config This module defines the configuration of the copper runtime.
The configuration is a directed graph where nodes are tasks and edges are connections between tasks.
The configuration is serialized in the RON format.
The configuration is used to generate the runtime code at compile time. context User-facing execution context passed to task and bridge process callbacks. copperlist CopperList is the main data structure used by Copper to communicate between tasks.
It is a queue that can be used to store preallocated messages between tasks in memory order. cuasynctask cubridge Typed bridge traits and helpers used to connect Copper to external components both as a sink
and a source. curuntime CuRuntime is the heart of what copper is running on the robot.
It is exposed to the user via the copper_runtime macro injecting it as a field in their application struct. cutask This module contains all the main definition of the traits you need to implement
or interact with to create a Copper task. debug CuDebug: lightweight time-travel debugger helpers on top of Copper logs. distributed_replay Discovery, validation, planning, and causal execution helpers for
distributed deterministic replay. logcodec memmap This is the memory map file implementation for the unified logger for Copper.
It is std only. monitoring Some basic internal monitoring tooling Copper uses to monitor itself and the components it runs. noop payload Copper-friendly payload helpers used in task messages and task-local caches. pool reflect Runtime reflection helpers built on top of bevy_reflect. reflect_serde Serde integration for reflected types. replay Shared Clap-backed helpers for replay and resimulation binaries. resource Resource descriptors and utilities to hand resources to tasks and bridges.
User view: in copperconfig.ron, map the binding names your tasks/bridges
expect to the resources exported by your board bundle. Exclusive things
(like a serial port) should be bound once; shared things (like a telemetry
bus Arc) can be bound to multiple consumers. simulation cu29::simulation Module__cu29_defmt_debug __cu29_defmt_error __cu29_defmt_info __cu29_defmt_warn __cu29_paste bundle_resources critical debug This macro is used to log a debug message with parameters.
The first parameter is a string literal that represents the message to be logged.
Only {} is supported as a placeholder for parameters.
The rest of the parameters are the values to be logged.
The parameters can be named or unnamed.
Named parameters are specified as name = value.
Unnamed parameters are specified as value. defmt_debug defmt_error defmt_info defmt_warn error 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 input_msg intern Interns a string
For example: output_msg resources rx_channels Declares the receive channels of a CuBridge tx_channels Declares the transmit channels of a CuBridge warning AlignedBuffer A buffer that is aligned to a specific size with the Element of type E. BincodeAdapter 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. BridgeChannel BridgeChannelConfig Runtime descriptor that includes the parsed per-channel configuration. BridgeChannelDescriptor Static metadata describing a channel. Used to pass configuration data at runtime without
leaking the channel’s payload type. BridgeConfig Declarative definition of a bridge component with a list of channels. BundleContext Context passed to bundle providers when building resources. BundleIndex Index identifying a resource bundle in the active mission. Cnx This represents a connection between 2 tasks (nodes) in the configuration graph. CodecState ComponentConfig 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. ComponentId Strongly-typed index into CuMonitoringMetadata::components ConfigError CopperLiskMask Not implemented yet.
This mask will be used to for example filter out necessary regions of a copper list between remote systems. CopperList CopperListEntry One message entry in CopperList slot order with resolved component identity. CopperListInfo CopperListIoStats Reported data about CopperList IO for a single iteration. CopperListLayout Static monitor-side CopperList indexing layout. CopperListView Per-loop monitor view over CopperList metadata paired with static component mapping. CountingAlloc A simple allocator that counts the number of bytes allocated and deallocated. CuArray Copper friendly wrapper for a fixed size array.
T: Clone is required because this type derives Reflect, and
the reflection path requires the reflected value to be cloneable. CuArrayVec A Copper-friendly wrapper around ArrayVec with bincode serialization support. CuCompactString 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. CuContextBuilder Builder for CuContext CuDebugSession CuDuration For Robot times, the underlying type is a u64 representing nanoseconds.
It is always positive to simplify the reasoning on the user side. CuDurationStatistics A Specialized statistics object for CuDuration.
It will also keep track of the jitter between the values. CuError Common copper Error type. CuExecutionLoop This structure represents a loop in the execution plan.
It is used to represent a sequence of Execution units (loop or steps) that are executed
multiple times.
if loop_count is None, the loop is infinite. CuExecutionStep This structure represents a step in the execution plan. CuGraph CuHandle A shareable handle to a pooled or detached object. CuHostMemoryPool A pool of host memory buffers. CuInputMsg CuInstant High-precision instant in time, represented as nanoseconds since an arbitrary epoch CuListSlot Strongly-typed CopperList slot index. CuListsManager 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. CuLogEntry This is the basic structure for a log entry in Copper. CuMonitoringMetadata Immutable runtime-provided metadata passed once to CuMonitor::new CuMonitoringRuntime Runtime-provided dynamic monitoring handles passed once to CuMonitor::new CuMsgIoCache CuMsgIoCaptureGuard CuMsgIoStats CuMsgMetadata CuMsgMetadata is a structure that contains metadata common to all CuStampedDataSet. CuMsgOrigin Origin metadata captured when a Copper-aware transport receives a remote message. CuNoBridgeChannels Empty channel set used when a simulated bridge has no channel on one side. CuOutputPack 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. CuRuntimeBuilder CuRuntimeParts CuSharedMemoryBuffer CuSharedMemoryHandleDescriptor CuSharedMemoryPool A pool of fixed-size shared-memory buffers that can be leased to a child
process without copying the underlying bytes. CuSimBridge Placeholder bridge used in simulation when a bridge is configured with
run_in_sim: false. CuSimSinkTask 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. CuSimSrcTask 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. CuStampedData CuMsg is the envelope holding the msg payload and the metadata between tasks. CuTimeRange Represents a time range. EffectiveConfigEntry EndOfLogMarker Payload stored in the end-of-log section to signal whether the log was cleanly closed. ExecutionMarker Execution progress marker emitted by the runtime before running a component step. IncludesConfig Includes are used to include other configuration files. InstanceConfigSetOperation One path-based config overlay applied to a parsed local Copper config. JumpOutcome 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. KeyFramesManager Manages the frozen tasks state and logging. LiveStatistics 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. LoggerRuntime The lifetime of this struct is the lifetime of the logger. LoggingCodecSpec LoggingConfig LoopRateLimiter Runtime loop limiter that preserves phase with absolute deadlines. MainHeader The main file header of the datalogger. MissionsConfig Missions are used to generate alternative DAGs within the same configuration. MonitorComponentMetadata Static identity entry for one monitored runtime component. MonitorConfig MonitorConnection MonitorExecutionProbe Platform-neutral monitor view of runtime execution progress. MonitorNode MonitorTopology MultiCopperConfig Strict umbrella configuration describing multiple Copper subsystems and their explicit links. MultiCopperEndpoint Typed endpoint reference used by validated multi-Copper interconnects. MultiCopperInterconnect Validated explicit interconnect between two subsystem endpoints. MultiCopperInterconnectConfig One explicit interconnect between two subsystem bridge channels. MultiCopperSubsystem Validated subsystem entry with its compiler-assigned numeric subsystem code and parsed local Copper config. MultiCopperSubsystemConfig 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. NodeLogging Configuration for logging in the node. NoopLogger NoopSectionStorage NullLog ObservedWriter A bincode writer wrapper that reports every encoded byte to Copper’s
observation counters. OptionCuTime 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. OwningIoWriter PanicHookRegistration PanicReport PartialCuTimeRange Represents a time range with possible undefined start or end or both. PayloadIoStats ReflectSerializer A general purpose serializer for reflected types. ResourceBindingMap Static mapping between user-defined binding ids and resource keys. ResourceBundleConfig Declarative definition of a resource bundle. ResourceKey Typed identifier for a resource entry. ResourceManager Manages the concrete resources available to tasks and bridges. RobotClock 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. RobotClockMock A mock clock that can be controlled by the user. RuntimeConfig RuntimeExecutionProbe Lock-free runtime-side progress probe. RuntimeLifecycleRecord One event record persisted in the UnifiedLogType::RuntimeLifecycle section. RuntimeLifecycleStackInfo Stack and process identification metadata persisted in the runtime lifecycle log. SectionCacheStats Section-cache statistics for a debug session. SectionHandle A SectionHandle is a handle to a section in the datalogger.
It allows tracking the lifecycle of the section. SectionHeader 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. SerializationData Contains data relevant to the automatic reflect powered (de)serialization of a type. SharedHandleSerializationGuard SimpleFileWriter 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. SyncCopperListsManager Manages the lifecycle of the copper lists and logging on the synchronous path. TaskOutputSpec Trait to trace back from the CopperList the origin of each message slot. ThreadPoolBundle TypeRegistry A registry of reflected types. TypedReflectSerializer A serializer for reflected types whose type will be known during deserialization. UnifiedLogStatus Basic statistics for the unified logger.
Note: the total_allocated_space might grow for the std implementation UnifiedLoggerBuilder Use this builder to create a new DataLogger. UnifiedLoggerIOReader This a convenience wrapper around the UnifiedLoggerRead to implement the Read trait. UnifiedLoggerRead A read side of the memory map based unified logger. UnifiedLoggerWrite A write side of the datalogger. AllocatedSection BridgeChannelConfigRepresentation Directional mapping for bridge channels. ComponentType Runtime component category used by monitoring metadata and topology. ConfigGraphs CopperListState Those are the possible states along the lifetime of a CopperList. CuBridgeLifecycleState Lifecycle callbacks for bridges when running in simulation. CuComponentState Lifecycle state of a monitored component. CuDirection A simple wrapper enum for petgraph::Direction,
designed to be converted into it via the From trait. CuExecutionUnit This structure represents a step in the execution plan. CuHandleInner A handle to a pooled or detached object. CuLatchedState Consumer-side cache updated by CuLatchedStateUpdate CuLatchedStateUpdate Producer-side update for a stateful value cached by downstream consumers. CuLogLevel Log levels for Copper. CuNoBridgeChannelId Empty channel-id enum used when a simulated bridge has no channel on one side. CuSharedMemoryElementType CuTaskCallbackState This is the state that will be passed to the simulation support to hook
into the lifecycle of the tasks. CuTaskType Copper tasks can be of 3 types: 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. OwnedCopperListSubmission Result of handing an owned boxed CopperList to the runtime-side CL I/O path. ProcessStepOutcome Control-flow result returned by one generated process stage. RuntimeLifecycleConfigSource Identifies where the effective runtime configuration came from. RuntimeLifecycleEvent Runtime lifecycle events emitted in the dedicated lifecycle section. SimOverride This is the answer the simulator can give to control the simulation flow. ThreadPoolId 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. TxEmptyPolicy Compile-time description of a single bridge channel, including the message type carried on it. TypeInfo Compile-time type information for various reflected types. UnifiedLogType Defines the types of what can be logged in the unified logger. UnifiedLogger Holds the read or write side of the datalogger. Value 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 ArrayLike BridgeChannelInfo Type-erased metadata exposed for channel enumeration and configuration. BridgeChannelSet Describes a set of channels for one direction (Tx or Rx) of the bridge. ClockProvider A trait to provide a clock to the runtime. CopperListTuple 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. CuDistributedReplayApplication Simulation-enabled applications that can be instantiated for distributed replay. CuListZeroedInit Initializes fields that cannot be zeroed after allocating a zeroed
CopperList CuLogCodec CuMonitor Runtime monitoring contract implemented by monitor components. CuMsgMetadataTrait Key metadata piece attached to every message in Copper. CuMsgPack CuMsgPayload The state of a task. CuPayloadRawBytes Provides per-output raw payload sizes aligned with ErasedCuStampedDataSet::cumsgs order. 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. CuRecordedReplayApplication Simulation-enabled applications that can replay a recorded CopperList verbatim. CuSimApplication A trait that defines the structure and behavior of a simulation-enabled CuApplication. CuSimSinkInput Helper to map a payload type (or tuple of payload types) to the corresponding input_msg! form. CuSinkTask A Sink Task is a task that only consumes messages. For example drivers for actuators are Sink Tasks. CuSrcTask 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. CuStdApplication Convenience trait for CuApplication when it is just a std App CuSubsystemMetadata 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. CurrentRuntimeCopperList Optional introspection hook exposing the latest runtime-generated CopperList snapshot. DeviceCuPool A device memory pool can copy data from a device to a host memory pool on top. ElementType Basic Type that can be used in a buffer in a CuPool. ErasedCuStampedData A generic trait to expose the generated CuStampedDataSet from the task graph. ErasedCuStampedDataSet 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. GetTypeRegistration A trait which allows a type to generate its TypeRegistrationTypeRegistry MatchingTasks Metadata Represent the minimum set of traits to be usable as Metadata in Copper. PayloadSchemas Trait for providing JSON schemas for CopperList payload types. PoolMonitor Trait for a Pool to exposed to be monitored by the monitoring API. Reflect A core trait of bevy_reflect ReflectTaskIntrospection Runtime task-reflect contract exposed by generated Copper applications. ReflectTypePath ResourceBindings 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" }). ResourceBundle Bundle providers implement this trait to populate the ResourceManager with
concrete resources for a given bundle id. ResourceBundleDecl Trait implemented by bundle providers to declare their resource id enum. ResourceId Trait implemented by resource id enums generated by bundle_resources!. SaturatingSub Saturating subtraction for time and duration types. SectionStorage A Storage is an append-only structure that can update a header section. Serialize A data structure that can be serialized into any data format supported
by Serde. TypePath A static accessor to type paths and names. UnifiedLogRead Read back a unified log linearly. UnifiedLogWrite The writing interface to the unified logger.
Writing is “almost” linear as various streams can allocate sections and track them until
they drop them. WriteStream Defines a basic write, append only stream trait to be able to log or send serializable objects. 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. compute_runtime_plan This is the main heuristics to compute an execution plan at compilation time.
TODO(gbin): Make that heuristic pluggable. decode_msg_with_codec deserialize_codec_config dump_type_registry_schema Dumps a stable, human-readable schema snapshot for the registered reflected types. effective_config_entry enable_shared_handle_serialization encode_msg_with_codec find_task_type_for_id 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 initialize instantiate_codec 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. perf_now Returns a monotonic instant used for local runtime performance timing. pools_statistics Get the list of pools and their statistics.
We use SmallVec here to avoid heap allocations while the stack is running. rate_target_period Convert a configured runtime rate target to an integer-nanosecond period. read_configuration Read a copper configuration from a file. read_configuration_str read_effective_config_ron_from_log 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.start found in a CopperList. register_live_log_listener Register a live log listener; subsequent logs invoke cb. No-op if runtime not initialized. resolve_task_output_codec runtime_panic_hook_active seed_effective_config_from_log set_effective_config_ron 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. with_codec_for_decode with_codec_for_encode AscIter AscIterMut BridgesInstantiator CopperListsManager CuMsg This is the robotics message type for Copper with the correct Metadata type
that will be used by the runtime. CuResult CuTime A robot time is just a duration from a fixed point in time. ExecutionProbeHandle Instant Iter IterMut LiveLogListener Callback signature: receives the structured entry plus its format string and param names. MonitorInstantiator NodeId NodeId is the unique identifier of a node in the configuration graph for petgraph
and the code generation. ProcessStepResult Result type used by generated process-step functions. TasksInstantiator 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.
if subsystem is provided, config must 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. Reflect The main derive macro used by bevy_reflect for deriving its Reflect trait. Serialize TypePath Derives the TypePath trait, providing a stable alternative to [std::any::type_name].