Struct Photon 

pub struct Photon { /* private fields */ }

Main Photon runtime handle.

Implementations

impl Photon

pub fn builder() -> PhotonBuilder

Start building a Photon runtime instance.

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.

Errors

Returns an error if the operation fails.

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 stream.

For typed topics, prefer TopicType::subscribe(opts) or the #[subscribe] macro. Runnable walkthrough: cargo run -p uf-photon --example manual_subscribe --features runtime,mem.

Example

use futures::StreamExt;
use photon_runtime::{configure, default, Photon};

configure(Photon::builder().auto_registry().build()?);
let photon = default().expect("configure first");
let mut stream = photon.subscribe("my.topic", None, None);
if let Some(result) = stream.next().await {
    let _event = result?;
}

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 (headless ops entry point).

Errors

Returns an error if the operation fails.

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

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

Requires an IdentityFactory (e.g. photon_core::JsonIdentityFactory) for actor resolution. Optionally call configure so convenience Type::publish() helpers work.

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.