Skip to main content

​
Transport Modes Overview

Publisher and Subscriber support two transport mechanisms:
  1. Local transport (iceoryx2): Zero-copy shared memory for same-process communication (< 1 μs latency)
  2. Network transport (Zenoh): Network-based messaging for cross-process and remote communication (1-10 ms latency)
Unlike TopicManager, which automatically selects the optimal transport, direct Publisher/Subscriber APIs require you to understand and control transport selection manually.

​
Subscriber Transport Selection

use cerulion_core::prelude::*;

// Auto-detect: tries local first, falls back to network
let subscriber = Subscriber::create("sensors/temperature", None)?;
Auto-detection logic:
  1. Check if local publisher exists (iceoryx2)
  2. If yes, use local transport (fast, zero-copy)
  3. If no, use network transport (Zenoh)
Auto-detection is the recommended approach for most use cases. It automatically chooses the fastest available transport.

​
Force Local Transport

use cerulion_core::prelude::*;

// Force local transport only
let subscriber = Subscriber::create("sensors/temperature", Some(false))?;
Forces the subscriber to use only local transport. This is useful when:
  • You’re certain a local publisher exists
  • You want to ensure zero-copy performance
  • You want to avoid network overhead
If you force local transport but no local publisher exists, receive() will always return None. Use this only when you’re certain a local publisher is running.

​
Force Network Transport

use cerulion_core::prelude::*;

// Force network transport only
let subscriber = Subscriber::create("sensors/temperature", Some(true))?;
Forces the subscriber to use only network transport. This is useful when:
  • You’re connecting to a remote publisher
  • You want to test network communication
  • You want to ensure network discovery works
Network transport is useful for:
  • Cross-process communication
  • Remote machines
  • When you want to ensure network discovery works

​
Enabling Local Transport After Creation

If you create a network-only subscriber but later want to enable local transport: 
use cerulion_core::prelude::*;

// Create network-only subscriber
let mut subscriber = Subscriber::create("sensors/temperature", Some(true))?;

// Later, enable local subscriber (e.g., when local publisher becomes available)
subscriber.enable_local_subscriber(None)?;
// Now subscriber can receive from both local and network publishers

​
Publisher Network Control

Publishers always use local transport. Network transport is optional and can be controlled at runtime: 
use cerulion_core::prelude::*;

// Create publisher with network disabled initially
let publisher = Publisher::create("sensors/temperature", false)?;

// Enable network later (e.g., when remote subscriber discovered)
publisher.enable_network();

// Check if network is enabled
if publisher.is_network_enabled() {
    println!("Network publishing is active");
}

// Disable network publishing
publisher.disable_network();
Network publishing runs on a background thread. When enabled, messages are queued and sent asynchronously. The network thread uses latest-message semantics, so only the most recent message is sent if the network is slow.

​
Transport Modes Comparison

ModeWhen to UseLatencySerializationControl
Auto-detectDefault choiceLocal: < 1 μs
Network: 1-10 ms		Local: None
Network: Yes		Automatic
Force localSame-machine only< 1 μsNoneManual
Force networkRemote or cross-process1-10 msYesManual

​
Comparison with TopicManager

TopicManager automatically handles transport selection:
FeatureDirect Publisher/SubscriberTopicManager
Transport SelectionManual (None, Some(true), Some(false))Automatic (auto-detects and switches)
Network EnableManual (enable_network() / disable_network())Automatic (enabled on discovery)
Local EnableManual (enable_local_subscriber())Automatic (enabled when local publisher appears)
ControlFine-grained per pub/subCentralized automatic management
TopicManager automatically:
  • Selects the optimal transport (local when available, network otherwise)
  • Enables network transport when remote subscribers are discovered
  • Switches to local transport when local publishers become available
  • Manages transport transitions seamlessly
Use direct Publisher/Subscriber APIs only if you need manual control over these behaviors.

​
When to Use Manual Control

Manual transport control is beneficial when:
  1. Runtime network control: You need to enable/disable network publishing based on application state
  2. Testing: You want to force specific transport modes for testing
  3. Resource management: You want to disable network to save resources when no remote subscribers exist
  4. Custom discovery: You’re implementing your own discovery mechanism
  5. Performance tuning: You need fine-grained control over transport selection for performance optimization

​
Next Steps

API Reference

Browse the complete API documentation

Best Practices

Learn recommended usage patterns

Overview

Return to Publisher/Subscriber overview

TopicManager

Use automatic transport management