use std::ops::{Deref, DerefMut};
use std::sync::Arc;
use std::time::Duration;
use tracing::Instrument as _;
use crate::error::Result;
use crate::runtime::Runtime;
pub type RebuildFn = dyn Fn() -> Result<Runtime> + Send + Sync;
#[derive(Clone)]
pub struct RuntimePool {
tx: async_channel::Sender<Runtime>,
rx: async_channel::Receiver<Runtime>,
rebuild: Option<Arc<RebuildFn>>,
companion: Option<Arc<dyn std::any::Any + Send + Sync>>,
}
impl std::fmt::Debug for RuntimePool {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("RuntimePool")
.field("size", &self.size())
.field("available", &self.rx.len())
.field("recycling", &self.rebuild.is_some())
.finish()
}
}
impl RuntimePool {
pub fn new(runtimes: Vec<Runtime>) -> Self {
Self::build(runtimes, None)
}
pub fn with_rebuild<F>(runtimes: Vec<Runtime>, rebuild: F) -> Self
where
F: Fn() -> Result<Runtime> + Send + Sync + 'static,
{
Self::build(runtimes, Some(Arc::new(rebuild)))
}
fn build(runtimes: Vec<Runtime>, rebuild: Option<Arc<RebuildFn>>) -> Self {
let (tx, rx) = async_channel::bounded(runtimes.len().max(1));
for rt in runtimes {
let _ = tx.try_send(rt);
}
Self {
tx,
rx,
rebuild,
companion: None,
}
}
#[must_use]
pub fn with_companion<T: std::any::Any + Send + Sync>(mut self, companion: T) -> Self {
self.companion = Some(Arc::new(companion));
self
}
pub fn companion<T: std::any::Any + Send + Sync>(&self) -> Option<&T> {
self.companion.as_deref()?.downcast_ref()
}
pub fn size(&self) -> usize {
self.tx.capacity().unwrap_or(0)
}
pub fn available(&self) -> usize {
self.rx.len()
}
pub async fn get(&self) -> RuntimeGuard {
#[allow(clippy::expect_used)]
let rt = self
.rx
.recv()
.await
.expect("runtime pool channel cannot be closed while the pool is alive");
self.guard(rt)
}
pub async fn get_timeout(&self, wait: Duration) -> Option<RuntimeGuard> {
let span = tracing::debug_span!(
"pool_checkout",
wait_ms = tracing::field::Empty,
outcome = tracing::field::Empty,
);
let started = (!span.is_disabled()).then(std::time::Instant::now);
let got = async {
if wait.is_zero() {
Some(self.get().await)
} else if let Ok(rt) = self.rx.try_recv() {
Some(self.guard(rt))
} else {
match tokio::time::timeout(wait, self.rx.recv()).await {
Ok(Ok(rt)) => Some(self.guard(rt)),
Ok(Err(_)) | Err(_) => None,
}
}
}
.instrument(span.clone())
.await;
if let Some(started) = started {
span.record("wait_ms", started.elapsed().as_millis() as u64);
span.record("outcome", if got.is_some() { "hit" } else { "shed" });
}
got
}
fn guard(&self, rt: Runtime) -> RuntimeGuard {
RuntimeGuard {
rt: Some(rt),
tx: self.tx.clone(),
rebuild: self.rebuild.clone(),
}
}
}
pub struct RuntimeGuard {
rt: Option<Runtime>,
tx: async_channel::Sender<Runtime>,
rebuild: Option<Arc<RebuildFn>>,
}
impl std::fmt::Debug for RuntimeGuard {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("RuntimeGuard")
.field("runtime", &self.rt)
.finish_non_exhaustive()
}
}
impl Deref for RuntimeGuard {
type Target = Runtime;
fn deref(&self) -> &Self::Target {
#[allow(clippy::expect_used)]
self.rt.as_ref().expect("runtime present until drop")
}
}
impl DerefMut for RuntimeGuard {
fn deref_mut(&mut self) -> &mut Self::Target {
#[allow(clippy::expect_used)]
self.rt.as_mut().expect("runtime present until drop")
}
}
impl Drop for RuntimeGuard {
fn drop(&mut self) {
let Some(rt) = self.rt.take() else {
return;
};
if !rt.is_poisoned() && !std::thread::panicking() {
let _ = self.tx.try_send(rt);
return;
}
let Some(rebuild) = self.rebuild.clone() else {
tracing::warn!("a damaged Lua state was returned to a pool without recycling");
let _ = self.tx.try_send(rt);
return;
};
drop(rt);
let tx = self.tx.clone();
let handle = tokio::task::spawn_blocking(move || match rebuild() {
Ok(fresh) => {
let _ = tx.try_send(fresh);
tracing::info!(outcome = "rebuilt", "recycled a damaged Lua state");
}
Err(err) => tracing::error!("failed to recycle a damaged Lua state: {err}"),
});
tokio::spawn(async move {
if let Err(err) = handle.await {
tracing::error!("the Lua state rebuild task panicked: {err}");
}
});
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::runtime::{Runtime, RuntimeOpts};
fn runtime() -> Runtime {
Runtime::new_with(RuntimeOpts {
libs: mlua::StdLib::STRING,
memory_limit: 8 * 1024 * 1024,
dev_mode: false,
exec_timeout: None,
package_dir: None,
extra_package_dirs: Vec::new(),
})
.expect("runtime")
}
#[tokio::test]
async fn checkout_returns_the_state_on_drop() {
let pool = RuntimePool::new(vec![runtime()]);
assert_eq!(pool.size(), 1);
{
let _guard = pool.get().await;
assert_eq!(pool.available(), 0);
}
assert_eq!(pool.available(), 1);
}
#[test]
fn a_companion_travels_with_the_pool_and_its_clones() {
let pool = RuntimePool::new(vec![runtime()]).with_companion(7u32);
assert_eq!(pool.clone().companion::<u32>(), Some(&7));
assert_eq!(pool.companion::<String>(), None);
assert_eq!(RuntimePool::new(vec![runtime()]).companion::<u32>(), None);
}
#[tokio::test]
async fn get_timeout_sheds_when_the_pool_is_busy() {
let pool = RuntimePool::new(vec![runtime()]);
let held = pool.get().await;
assert!(pool.get_timeout(Duration::from_millis(50)).await.is_none());
drop(held);
assert!(pool.get_timeout(Duration::from_millis(50)).await.is_some());
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn poisoned_states_are_rebuilt_not_reused() {
let pool = RuntimePool::with_rebuild(vec![runtime()], || Ok(runtime()));
{
let mut guard = pool.get().await;
guard.poison();
}
let guard = tokio::time::timeout(Duration::from_secs(5), pool.get())
.await
.expect("a replacement state must be built");
assert!(!guard.is_poisoned());
}
}