Struct ockam_node::Context
source · [−]pub struct Context { /* private fields */ }
Expand description
Context contains Node state and references to the runtime.
Implementations
sourceimpl Context
impl Context
sourcepub fn aliases(&self) -> AddressSet
pub fn aliases(&self) -> AddressSet
Return all addresses of the current worker
sourcepub async fn new_context<S: Into<Address>>(&self, addr: S) -> Result<Context>
pub async fn new_context<S: Into<Address>>(&self, addr: S) -> Result<Context>
Create a new context without spawning a full worker
Note: this function is very low-level. For most users
start_worker()
is the recommended to
way to create a new worker context.
sourcepub async fn start_worker<NM, NW, S>(
&self,
address: S,
worker: NW
) -> Result<()> where
S: Into<AddressSet>,
NM: Message + Send + 'static,
NW: Worker<Context = Context, Message = NM>,
pub async fn start_worker<NM, NW, S>(
&self,
address: S,
worker: NW
) -> Result<()> where
S: Into<AddressSet>,
NM: Message + Send + 'static,
NW: Worker<Context = Context, Message = NM>,
Start a new worker instance at the given address set
A worker is an asynchronous piece of code that can send and
receive messages of a specific type. This type is encoded via
the Worker
trait. If your code relies
on a manual run-loop you may want to use
start_processor()
instead!
Each address in the set must be unique and unused on the
current node. Workers must implement the Worker trait and be
thread-safe. Workers run asynchronously and will be scheduled
independently of each other. To wait for the initialisation
of your worker to complete you can use
wait_for()
.
use ockam_core::{Result, Worker, worker};
use ockam_node::Context;
struct MyWorker;
#[worker]
impl Worker for MyWorker {
type Context = Context;
type Message = String;
}
async fn start_my_worker(ctx: &mut Context) -> Result<()> {
ctx.start_worker("my-worker-address", MyWorker).await
}
sourcepub async fn start_worker_with_access_control<NM, NW, NA, S>(
&self,
address: S,
worker: NW,
access_control: NA
) -> Result<()> where
S: Into<AddressSet>,
NM: Message + Send + 'static,
NW: Worker<Context = Context, Message = NM>,
NA: AccessControl,
pub async fn start_worker_with_access_control<NM, NW, NA, S>(
&self,
address: S,
worker: NW,
access_control: NA
) -> Result<()> where
S: Into<AddressSet>,
NM: Message + Send + 'static,
NW: Worker<Context = Context, Message = NM>,
NA: AccessControl,
Start a new worker instance with explicit access controls
sourcepub async fn start_processor<P>(
&self,
address: impl Into<Address>,
processor: P
) -> Result<()> where
P: Processor<Context = Context>,
pub async fn start_processor<P>(
&self,
address: impl Into<Address>,
processor: P
) -> Result<()> where
P: Processor<Context = Context>,
Start a new processor instance at the given address set
A processor is an asynchronous piece of code that runs a
custom run loop, with access to a worker context to send and
receive messages. If your code is built around responding to
message events, consider using
start_worker()
instead!
sourcepub async fn stop_worker<A: Into<Address>>(&self, addr: A) -> Result<()>
pub async fn stop_worker<A: Into<Address>>(&self, addr: A) -> Result<()>
Shut down a local worker by its primary address
sourcepub async fn stop_processor<A: Into<Address>>(&self, addr: A) -> Result<()>
pub async fn stop_processor<A: Into<Address>>(&self, addr: A) -> Result<()>
Shut down a local processor by its address
sourcepub async fn stop_now(&mut self) -> Result<()>
pub async fn stop_now(&mut self) -> Result<()>
Signal to the local runtime to shut down immediately
WARNING: calling this function may result in data loss.
It is recommended to use the much safer
Context::stop
function instead!
sourcepub async fn stop(&mut self) -> Result<()>
pub async fn stop(&mut self) -> Result<()>
Signal to the local runtime to shut down
This call will hang until a safe shutdown has been completed.
The default timeout for a safe shutdown is 1 second. You can
change this behaviour by calling
Context::stop_timeout
directly.
sourcepub async fn stop_timeout(&mut self, seconds: u8) -> Result<()>
pub async fn stop_timeout(&mut self, seconds: u8) -> Result<()>
Signal to the local runtime to shut down
This call will hang until a safe shutdown has been completed or the desired timeout has been reached.
sourcepub async fn send_and_receive<R, M, N>(&self, route: R, msg: M) -> Result<N> where
R: Into<Route>,
M: Message + Send + 'static,
N: Message,
pub async fn send_and_receive<R, M, N>(&self, route: R, msg: M) -> Result<N> where
R: Into<Route>,
M: Message + Send + 'static,
N: Message,
Using a temporary new context, send a message and then receive a message
This helper function uses new_context
, send
, and
receive
internally. See their documentation for more
details.
sourcepub async fn send_to_self<A, M>(&self, from: A, addr: A, msg: M) -> Result<()> where
A: Into<Address>,
M: Message + Send + 'static,
pub async fn send_to_self<A, M>(&self, from: A, addr: A, msg: M) -> Result<()> where
A: Into<Address>,
M: Message + Send + 'static,
Send a message to another address associated with this worker
This function is a simple wrapper around Self::send()
which
validates the address given to it and will reject invalid
addresses.
sourcepub async fn send<R, M>(&self, route: R, msg: M) -> Result<()> where
R: Into<Route>,
M: Message + Send + 'static,
pub async fn send<R, M>(&self, route: R, msg: M) -> Result<()> where
R: Into<Route>,
M: Message + Send + 'static,
Send a message to an address or via a fully-qualified route
Routes can be constructed from a set of Address
es, or via
the RouteBuilder
type. Routes can contain middleware
router addresses, which will re-address messages that need to
be handled by specific domain workers.
use ockam_core::Message;
use serde::{Serialize, Deserialize};
#[derive(Message, Serialize, Deserialize)]
struct MyMessage(String);
impl MyMessage {
fn new(s: &str) -> Self {
Self(s.into())
}
}
ctx.send("my-test-worker", MyMessage::new("Hello you there :)")).await?;
Ok(())
sourcepub async fn send_from_address<R, M>(
&self,
route: R,
msg: M,
sending_address: Address
) -> Result<()> where
R: Into<Route>,
M: Message + Send + 'static,
pub async fn send_from_address<R, M>(
&self,
route: R,
msg: M,
sending_address: Address
) -> Result<()> where
R: Into<Route>,
M: Message + Send + 'static,
Send a message to an address or via a fully-qualified route
Routes can be constructed from a set of Address
es, or via
the RouteBuilder
type. Routes can contain middleware
router addresses, which will re-address messages that need to
be handled by specific domain workers.
This function additionally takes the sending address parameter, to specify which of a worker’s (or processor’s) addresses should be used.
sourcepub async fn forward(&self, local_msg: LocalMessage) -> Result<()>
pub async fn forward(&self, local_msg: LocalMessage) -> Result<()>
Forward a transport message to its next routing destination
Similar to Context::send
, but taking a
TransportMessage
, which contains the full destination
route, and calculated return route for this hop.
Note: you most likely want to use
Context::send
instead, unless you are writing an
external router implementation for ockam node.
sourcepub async fn receive_block<M: Message>(&mut self) -> Result<Cancel<'_, M>>
pub async fn receive_block<M: Message>(&mut self) -> Result<Cancel<'_, M>>
Block the current worker to wait for a typed message
Warning this function will wait until its running ockam
node is shut down. A safer variant of this function is
receive
and
receive_timeout
.
sourcepub async fn receive<M: Message>(&mut self) -> Result<Cancel<'_, M>>
pub async fn receive<M: Message>(&mut self) -> Result<Cancel<'_, M>>
Block the current worker to wait for a typed message
This function may return a Err(FailedLoadData)
if the
underlying worker was shut down, or Err(Timeout)
if the call
was waiting for longer than the default timeout
. Use
receive_timeout
to adjust the
timeout period.
Will return None
if the corresponding worker has been
stopped, or the underlying Node has shut down.
sourcepub async fn receive_timeout<M: Message>(
&mut self,
timeout_secs: u64
) -> Result<Cancel<'_, M>>
pub async fn receive_timeout<M: Message>(
&mut self,
timeout_secs: u64
) -> Result<Cancel<'_, M>>
Wait to receive a message up to a specified timeout
See receive
for more details.
sourcepub async fn receive_match<M, F>(&mut self, check: F) -> Result<Cancel<'_, M>> where
M: Message,
F: Fn(&M) -> bool,
pub async fn receive_match<M, F>(&mut self, check: F) -> Result<Cancel<'_, M>> where
M: Message,
F: Fn(&M) -> bool,
Block the current worker to wait for a message satisfying a conditional
Will return Err
if the corresponding worker has been
stopped, or the underlying node has shut down. This operation
has a default timeout.
Internally this function uses receive
, so
is subject to the same timeout.
sourcepub async fn set_cluster<S: Into<String>>(&self, label: S) -> Result<()>
pub async fn set_cluster<S: Into<String>>(&self, label: S) -> Result<()>
Assign the current worker to a cluster
A cluster is a set of workers that should be stopped together when the node is stopped or parts of the system are reloaded. This is not to be confused with supervisors!
By adding your worker to a cluster you signal to the runtime that your worker may be depended on by other workers that should be stopped first.
Your cluster name MUST NOT start with _internals.
or
ockam.
!
Clusters are de-allocated in reverse order of their initialisation when the node is stopped.
sourcepub async fn list_workers(&self) -> Result<Vec<Address>>
pub async fn list_workers(&self) -> Result<Vec<Address>>
Return a list of all available worker addresses on a node
sourcepub async fn register<A: Into<Address>>(
&self,
type_: TransportType,
addr: A
) -> Result<()>
pub async fn register<A: Into<Address>>(
&self,
type_: TransportType,
addr: A
) -> Result<()>
Register a router for a specific address type
sourcepub async fn set_access_control(&mut self) -> Result<()>
pub async fn set_access_control(&mut self) -> Result<()>
Set access control for current context
Trait Implementations
sourceimpl AsyncTryClone for Context
impl AsyncTryClone for Context
Auto Trait Implementations
impl !RefUnwindSafe for Context
impl Send for Context
impl Sync for Context
impl Unpin for Context
impl !UnwindSafe for Context
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more