Struct BotFarm 

pub struct BotFarm<S> { /* private fields */ }

Available on crate feature farm only.

Implementations

impl<C: ClientApi, P: EventParser> BotFarm<Init<C, P>>

pub async fn init( farm_name: String, client: C, events: EventStream<P>, ) -> Result<Self, C::Error>

The farm_name is the name of the special bot managing the bot farm, it cannot be accessed directly. It is mostly used as an intermediary user deleting other users under the hood.

pub fn users_count(&self) -> usize

Total users count on the farm excluding the farm user

pub fn users(&self) -> impl Iterator<Item = &User>

Iterate over all users excluding the farm user

pub fn user(&self, name: &str) -> Option<&User>

pub async fn remove(&mut self, user_id: UserId) -> Result<(), C::Error>

pub async fn remove_by_name(&mut self, name: &str) -> Result<(), C::Error>

pub async fn prepare_bot( &mut self, settings: BotSettings, ) -> Result<UserId, CreateError<C::Error>>

where C: Clone,

Prepare a user with its own event stream. Use take_bot to extract the bot then.

pub async fn prepare_ghost( &mut self, settings: BotSettings, ) -> Result<UserId, CreateError<C::Error>>

where C: Clone,

Prepare a ghost user. Ghosts don’t have their own event streams, all their events end up in the general bot farm stream.

pub fn run(self) -> (BotFarm<Running<C, P>>, EventStream<P>)

where C: 'static + Send, C::Error: Send, P: 'static + Send,

Transition the farm to the running state by starting dispatching and routing events.

Returns a running farm and a general EventStream that receives:

• events belonging to ghost users
• general events not addressed to a specific user(events without User struct)

Farm user events are filtered out

Handle events or discard the returned event stream to avoid memory leaks.

impl<C: 'static + ClientApi, P: EventParser> BotFarm<Running<C, P>>

where C::Error: Send,

pub fn ghost(&self, user_id: UserId) -> Option<FarmBot<C>>

Return a ghost handle for user_id, or None if the user does not exist or is a bot.

Each call produces a new independent FarmBot handle. Multiple handles for the same ghost share the underlying command channel and with the xftp feature enabled the same download table, so concurrent download_file calls on different handles will work correctly.

pub fn take_bot(&self, user_id: UserId) -> (FarmBot<C>, EventStream<P>)

Take the bot handle and its EventStream out of the farm.

This is a one-shot operation: the internal event receiver is consumed and cannot be taken again. Panics if user_id is unknown, was registered as a ghost, or was already taken. Use take_bot_checked to avoid the panic.

pub fn take_bot_checked( &self, user_id: UserId, ) -> Option<(FarmBot<C>, EventStream<P>)>

Non-panicking variant of take_bot. Returns None if the user is unknown, is a ghost, or was already taken.

pub async fn create_bot( &self, settings: BotSettings, ) -> Result<(FarmBot<C>, EventStream<P>), CreateError<C::Error>>

Create a new SimpleX user, as a bot, and return its handle and event stream.

Unlike prepare_bot, this is available at runtime after run. In order to route events correctly all event streams are paused and don’t receive any events during the bot creation process.

pub async fn get_or_create_bot( &self, settings: BotSettings, ) -> Result<(FarmBot<C>, EventStream<P>), CreateError<C::Error>>

Return the existing bot if a user with the given display name is already known, otherwise create one via create_bot.

Eventual consistency

This method is eventually consistent and may return CreateError::Desync if the same bot is getting created/deleted from multiple threads. You’re supposed to retry this call to get the actual result on CreateError::Desync

pub async fn create_ghost( &self, settings: BotSettings, ) -> Result<FarmBot<C>, CreateError<C::Error>>

Create a new SimpleX user, register it as a ghost, and return a handle to it.

The ghost’s events are routed to the general EventStream returned when running a farm.

pub async fn get_or_create_ghost( &self, settings: BotSettings, ) -> Result<FarmBot<C>, CreateError<C::Error>>

Return a ghost handle for the named user if it already exists, otherwise create one via create_ghost.

Same eventual consistency caveats as get_or_create_bot.

pub async fn delete(&self, user_id: UserId) -> Result<(), C::Error>

Permanently delete a user and remove it from the routing table.

Any FarmBot handles that were already taken for this user remain alive but all subsequent commands on them will fail with an API error.

Trait Implementations

impl<S: Clone> Clone for BotFarm<S>

fn clone(&self) -> BotFarm<S>

Returns a duplicate of the value.

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

Performs copy-assignment from source.