Struct Photon 

pub struct Photon { /* private fields */ }

Main Photon runtime handle.

Keep this value alive for the lifetime of the process that publishes or runs handlers. Build it once with Photon::builder, pass it to publish_on / subscribe_on, and call start_executor on Mode 1 hosts and Mode 2 worker binaries.

Role	What to call
Publisher (Mode 2)	publish_on(&photon) — usually no executor
Worker (Mode 2)	start_executor + #[subscribe]
Embedded (Mode 1)	both publish and start_executor

Getting started: Mode 1, Mode 2.

Example

use std::sync::Arc;

use photon_core::JsonIdentityFactory;
use photon_runtime::Photon;

let photon = Photon::builder().auto_registry().build()?;
photon.start_executor(Arc::new(JsonIdentityFactory))?;

Implementations

impl Photon

pub fn builder() -> PhotonBuilder

Start building a Photon runtime instance.

See crate::builder::PhotonBuilder for Mode 1 / Mode 2 wiring.

pub fn backend_label(&self) -> &'static str

Telemetry label for the installed backend.

pub async fn admin_snapshot(&self) -> Result<AdminSnapshot>

Compose a read-only ops introspection snapshot for host admin UIs.

Aggregates the topic catalog, handler inventory, backend capabilities, and checkpoint cursors for inventory-registered handlers. Does not touch publish/subscribe hot paths.

Errors

Returns an error if a checkpoint load fails.

pub async fn publish( &self, topic_name: &str, topic_key: Option<&str>, actor_json: Value, payload_json: Value, ) -> Result<String>

Publish a single event to a topic by name (low-level).

Prefer the typed API generated by topic: EventType { … }.publish_on(&photon).await.

Example

// After #[topic(name = "orders.created")] on OrderCreated:
OrderCreated {
    order_id: "ord-1".into(),
    amount_cents: 9900,
}
.publish_on(&photon)
.await?;

Errors

Returns an error if the storage adapter rejects the append.

pub fn subscribe( &self, topic_name: &str, topic_key_filter: Option<&str>, after_seq: Option<i64>, ) -> Pin<Box<dyn Stream<Item = Result<Event>> + Send>>

Subscribe to topic events as a raw JSON stream (low-level).

Prefer the typed API from topic: EventType::subscribe_on(&photon, opts), or inventory handlers via #[subscribe] + start_executor.

Runnable typed stream: cargo run -p uf-photon --example keyed_topic --features runtime,mem. Runnable raw stream: cargo run -p uf-photon --example manual_subscribe --features runtime,mem.

Example (typed — preferred)

use futures::StreamExt;
use photon::{SubscribeOpts, topic};

#[topic(name = "orders.created")]
struct OrderCreated { order_id: String }

let mut stream = OrderCreated::subscribe_on(
    photon,
    SubscribeOpts::default_ephemeral(),
)
.await?;
if let Some(Ok(envelope)) = stream.next().await {
    let _ = envelope.payload.order_id;
}

pub fn subscribe_consumer_group( &self, topic_name: &str, shard_ids: &[u32], after_seq_by_shard: HashMap<u32, Option<i64>>, ) -> Pin<Box<dyn Stream<Item = Result<Event>> + Send>>

Subscribe to assigned virtual shards for a consumer group (multiplexed stream).

pub async fn get_event(&self, event_id: &str) -> Result<Option<Event>>

Load a specific event by ID.

Errors

Returns an error if the operation fails.

pub fn registry(&self) -> &TopicRegistry

Return the registered topic catalog.

pub async fn get_checkpoint_seq( &self, subscription_name: &str, topic_name: &str, topic_key: Option<&str>, ) -> Result<Option<i64>>

Read the last checkpoint sequence for a subscription/topic pair.

Errors

Returns an error if the operation fails.

pub async fn set_checkpoint( &self, subscription_name: &str, topic_name: &str, topic_key: Option<&str>, last_seq: i64, ) -> Result<()>

Persist an updated checkpoint sequence for a subscription/topic pair.

Errors

Returns an error if the operation fails.

pub const fn runtime(&self) -> &PhotonRuntimeState

Shared tailer / executor services.

pub async fn reclaim_transport(&self) -> Result<Vec<ReclaimReport>>

Reclaim transport log rows past the safe watermark (ops / retention entry point).

Call periodically (or from a headless ops job) after durable subscribers have advanced checkpoints. Retention knobs: crate config (PHOTON_TRANSPORT_* / builder retention_policy).

Errors

Returns an error if a storage reclaim operation fails.

pub fn start_executor(&self, identity: Arc<dyn IdentityFactory>) -> Result<()>

Start inventory-registered #[photon::subscribe] handlers.

Required on Mode 1 hosts and Mode 2 worker binaries. Publisher-only Mode 2 processes typically skip this. Requires an IdentityFactory (e.g. photon_core::JsonIdentityFactory for examples/tests) for actor reconstruction.

See Getting started → Mode 2.

Example

use std::sync::Arc;

use photon_core::JsonIdentityFactory;
use photon_runtime::Photon;

let photon = Photon::builder().auto_registry().build()?;
photon.start_executor(Arc::new(JsonIdentityFactory))?;
photon.shutdown_executor();
photon.join_executor().await;

Errors

Returns an error if the executor was already started on this runtime.

pub fn shutdown_executor(&self)

Signal handler loops to stop accepting new events.

Contract

Idempotent. Pair with Self::join_executor to await in-flight work.

pub async fn join_executor(&self)

Await handler loops and in-flight dispatches after Self::shutdown_executor.

Contract

Safe when the executor was never started. Restart requires a new Photon build.

Trait Implementations

impl Clone for Photon

fn clone(&self) -> Photon

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.