feat: Make mailbox sizes configurable with sensible defaults (#149)

Author: artrixdotdev

crates/libtortillas/src/engine/actor.rs

@@ -48,6 +48,9 @@ pub struct EngineActor {
    pub(crate) actor_ref: ActorRef<EngineActor>,
 
    pub(crate) default_piece_storage_strategy: PieceStorageStrategy,
+
+   /// Mailbox size for each torrent instance
+   pub(crate) mailbox_size: usize,
 }
 
 pub(crate) type EngineActorArgs = (
@@ -60,6 +63,11 @@ pub(crate) type EngineActorArgs = (
    Option<PeerId>,
    // Strategy for storing pieces of the torrent.
    PieceStorageStrategy,
+   // Mailbox size for each torrent instance
+   // Defaults to 64
+   //
+   // If 0 is provided, the mailbox size will be unbounded
+   Option<usize>,
 );
 
 impl Actor for EngineActor {
@@ -78,7 +86,8 @@ impl Actor for EngineActor {
    async fn on_start(
       args: Self::Args, actor_ref: kameo::prelude::ActorRef<Self>,
    ) -> Result<Self, Self::Error> {
-      let (tcp_addr, utp_addr, udp_addr, peer_id, default_piece_storage_strategy) = args;
+      let (tcp_addr, utp_addr, udp_addr, peer_id, default_piece_storage_strategy, mailbox_size) =
+         args;
 
       let tcp_addr = tcp_addr.unwrap_or_else(|| SocketAddr::from(([0, 0, 0, 0], 0)));
       // Should this be port 6881?
@@ -102,6 +111,7 @@ impl Actor for EngineActor {
          peer_id,
          actor_ref,
          default_piece_storage_strategy,
+         mailbox_size: mailbox_size.unwrap_or(64),
       })
    }
 

crates/libtortillas/src/engine/messages.rs

@@ -2,7 +2,7 @@ use kameo::{
    Actor, Reply, mailbox,
    prelude::{ActorRef, Context, Message},
 };
-use tracing::error;
+use tracing::{error, warn};
 
 use super::EngineActor;
 use crate::{
@@ -105,7 +105,17 @@ impl Message<EngineRequest> for EngineActor {
                   None,
                   self.default_piece_storage_strategy.clone(),
                ),
-               mailbox::unbounded(),
+               // if the size is 0, we use an unbounded mailbox
+               match self.mailbox_size {
+                  0 => {
+                     warn!(
+                        ?info_hash,
+                        "Spawning torrent with unbounded mailbox; this could drastically increase memory usage"
+                     );
+                     mailbox::unbounded()
+                  }
+                  size => mailbox::bounded(size),
+               },
             );
 
             self.actor_ref.link(&torrent_ref).await;

crates/libtortillas/src/engine/mod.rs

@@ -100,13 +100,28 @@ impl Engine {
       /// Strategy for storing pieces of the torrent.
       #[builder(default)]
       piece_storage_strategy: PieceStorageStrategy,
+      /// The mailbox size for each torrent instance.
+      ///
+      /// In simple terms, this is the number of messages that each torrent
+      /// instance can have in queue.
+      ///
+      /// If `Some(0)` is provided, the mailbox will be unbounded (no limit).
+      /// If `None` is provided, a sensible default is used.
+      ///
+      /// Higher values increase memory usage but reduce sender backpressure
+      /// when the mailbox is busy, which can improve throughput. Lower values
+      /// do the inverse.
+      ///
+      /// Default: `64` when `None` is provided.
+      mailbox_size: Option<usize>,
    ) -> Self {
       let args: EngineActorArgs = (
          tcp_addr,
          utp_addr,
          udp_addr,
          Some(custom_id),
          piece_storage_strategy,
+         mailbox_size,
       );
 
       let actor = EngineActor::spawn(args);