Skip to main content

​
Conceptual Introduction

TopicManager is the preferred way to do pub/sub in Cerulion Core. It provides automatic discovery, shared session management, centralized control, and type safety. Use this direct Publisher/Subscriber API only if you need fine-grained control over the pub/sub lifecycle that TopicManager doesn’t provide.
The direct Publisher and Subscriber APIs give you low-level control over messaging in Cerulion Core. Unlike TopicManager, which handles discovery, session management, and transport selection automatically, these APIs require you to manage these aspects manually.

Manual Control

Fine-grained control over network enable/disable, session management, and transport selection

Raw Bytes

Work directly with raw bytes - you handle serialization/deserialization yourself

Direct Access

Direct access to iceoryx2 listeners and low-level transport mechanisms

Custom Sessions

Create and manage your own Zenoh sessions and iceoryx2 nodes
When to use direct Publisher/Subscriber:
  • You need runtime control over network enable/disable per publisher
  • You want to manage your own Zenoh sessions and iceoryx2 nodes
  • You need direct access to iceoryx2 listeners for event-based programming
  • You’re building a custom abstraction layer on top of Cerulion Core
  • You need to share sessions across multiple independent components
When to use TopicManager instead:
  • You want automatic discovery and transport selection (recommended for most use cases)
  • You want shared session management to reduce resource overhead
  • You want centralized management of multiple topics
  • You prefer working with typed messages rather than raw bytes

​
Key Behaviors and Guarantees

  • receive() never blocks - Always returns immediately with Ok(Some(bytes)), Ok(None), or Err(e)
  • Messages are raw bytes - You must handle serialization and deserialization yourself
  • Local transport is always available - Publishers always use iceoryx2 for local communication
  • Network transport is optional - Can be enabled/disabled at runtime per publisher
  • Latest-message semantics for network - If network is slow, only the most recent message is sent
  • Manual session management - You create and manage Zenoh sessions and iceoryx2 nodes

​
Comparison with TopicManager

FeatureDirect Publisher/SubscriberTopicManager
DiscoveryManualAutomatic
Session ManagementManual (per pub/sub)Shared (centralized)
Transport SelectionManualAutomatic
Type SafetyRuntime (deserialization)Compile-time + Runtime
Message FormatRaw bytesTyped messages
Network ControlPer-publisher enable/disableAutomatic on discovery
Resource UsageHigher (multiple sessions)Lower (shared session)
ComplexityHigherLower

​
Next Steps

Quickstart

Get started with a complete working example

API Reference

Browse the complete API documentation

Transport Modes

Understand transport selection and control

Best Practices

Learn recommended usage patterns

Error Handling

Common errors and troubleshooting

TopicManager

Use the preferred automatic management approach