Struct station::process::Process

pub struct Process { /* private fields */ }

Process helper for RPC and PubSub communication.

The station library’s RPC and PubSub clients/servers require a bit of manual tuning. However, the Process helper and configuration system simplifies this. Unless specified in a config, networking for RPCs and PubSub channels are automatically generated Unix sockets based on the process name and the RPC/PubSub channel name. This allows for easy communication between processes on the same machine and being specific about configuring endpoints for processes on two different machines.

Implementations

impl Process

pub fn from_config_file(
    name: &str,
    config_path: &Path
) -> Result<Process, IoError>

Create a new Process from a config file.

Args:

• name: The name to associate the process with. Best practice is that process names should be unique, as per the convention for automatically defining Unix socket paths.
• config_path: Path to the YAML process/station configuration. This must exist even if no RPC or PubSub channels are defined in it. The directory containing this path must be writable by the user ID creating the Process instance. Any RPC method listed in the config at this path must be named as <process_name>.<rpc_name> in order for Process to find TCP configurations when calling RPCs implemented as TCP sockets.

pub fn new(
    name: &str,
    run_directory: &Path,
    config: &Config
) -> Result<Process, IoError>

Create a new Process with a config and run directory.

Args:

• name: The name to associate the process with. Best practice is that process names should be unique, as per the convention for automatically defining Unix socket paths.
• run_directory: Path to where Unix sockets will be created for this process.
• config: A process/station configuration defining TCP interfaces.

pub fn without_run_dir(name: &str, config: &Config) -> Process

Create a new Process from without a run directory.

Because the config has been pre-loaded and no run directory has been specified, the Process instance returned by this will not support RPC/PubSub with Unix sockets.

Args:

• name: The name to associate the process with. Best practice is that process names should be unique, as per the convention for automatically defining Unix socket paths.
• config: A process/station configuration defining TCP interfaces.

pub fn call_rpc<T, U>(
    &self,
    process_name: &str,
    rpc_name: &str,
    request: T,
    timeout: Duration
) -> Result<U, RpcError> where
    T: Debug + DeserializeOwned + Serialize + 'static,
    U: Debug + DeserializeOwned + Serialize + 'static, 

Call an RPC.

This function allows one to make a request to an RPC and get either the result of the call or an error returned. If the RPC endpoint is not listed in the config, it is assumed to be a Unix socket. If the endpoint does not exist, the RPC call will time out. The types for request T and response U must match waht the RPC server at the endpoint expects or an error may occur.

Args:

• process_name: The name of the Process instance running the RPC server.
• rpc_name: The name of the RPC running inside the target Process.
• request: The data to pass into the RPC request.
• timeout: The expected maximum duration of the RPC call.

Returns either the result of the RPC call on success or an RpcError on failure.

pub fn create_rpc<T, U>(
    &mut self,
    name: &'static str,
    callback: RpcCallback<T, U>
) -> Result<(), IoError> where
    T: Debug + DeserializeOwned + Serialize + 'static,
    U: Debug + DeserializeOwned + Serialize + 'static, 

Create an RPC server.

If the RPC server is defined in the config the Process was initialized with, and the IP address in the config is localhost, then the RPC server is a TCP endpoint. If the address for the RPC server is not a localhost address, an error is returned. IF the RPC server is not listed in the config, then the endpoint is a Unix socket based on the RPC name, Process name, and config path.

Args:

• name: The name to assign the RPC so clients can call it.
• callback: The function that is called when the RPC server receives data.

pub fn publish_to_topic<T>(&self, topic: &str, message: &T) -> Result<(), IoError> where
    T: Debug + DeserializeOwned + Serialize + 'static, 

Publish a message to a topic.

The topic must be defined in the Process config. Additionally, if publishing to a Unix socket, the run directory for the proces must exist.

Args:

• topic: The PubSub topic to publish to.
• message: The data to publish.

pub fn subscribe_to_topic<T>(
    &mut self,
    topic: &str,
    callback: PubSubCallback<T>
) -> Result<(), IoError> where
    T: Debug + DeserializeOwned + Serialize + 'static, 

Subscribe to a topic.

The topic must be defined in the Process config and there must be an endpoint listed for the Process name. If the endpoint is a UDP endpoint, it must be a local address. Additionally, if the topic has already been subscribed to, an error will be returned.

Args:

• topic: The PubSub topic to subscribe to.
• callback: The function that is called when the PubSub subscriber receives data.

pub fn name(&self) -> String

Return the name of the Process instance.