rquickjs_core/context/

async.rs

use super::{
    intrinsic,
    owner::{ContextOwner, DropContext},
    ContextBuilder, Intrinsic,
};
use crate::{markers::ParallelSend, qjs, runtime::AsyncRuntime, Ctx, Error, Result};
use core::{mem, ptr::NonNull};

mod future;

use future::WithFuture;

/// A macro for safely using an asynchronous context while capturing the environment.
///  
///  This macro was used to work around the lack of async closures, with the stabilization of async
///  closures this macro is now deprecated.
///  
///  Use the [`AsyncContext::async_with`] function instead.
///
/// # Usage
/// ```
/// # use rquickjs::{prelude::*, Function, async_with, AsyncRuntime, AsyncContext, Result};
/// # use std::time::Duration;
/// # async fn run(){
/// let rt = AsyncRuntime::new().unwrap();
/// let ctx = AsyncContext::full(&rt).await.unwrap();
///
/// // In order for futures to convert to JavaScript promises they need to return `Result`.
/// async fn delay<'js>(amount: f64, cb: Function<'js>) -> Result<()> {
///     tokio::time::sleep(Duration::from_secs_f64(amount)).await;
///     cb.call::<(), ()>(());
///     Ok(())
/// }
///
/// fn print(text: String) -> Result<()> {
///     println!("{}", text);
///     Ok(())
/// }
///
/// let mut some_var = 1;
/// // closure always moves, so create a ref.
/// let some_var_ref = &mut some_var;
/// async_with!(ctx => |ctx|{
///     
///     // With the macro you can borrow the environment.
///     *some_var_ref += 1;
///
///     let delay = Function::new(ctx.clone(),Async(delay))
///         .unwrap()
///         .with_name("delay")
///         .unwrap();
///
///     let global = ctx.globals();
///     global.set("print",Func::from(print)).unwrap();
///     global.set("delay",delay).unwrap();
///     ctx.eval::<(),_>(r#"
///         print("start");
///         delay(1,() => {
///             print("delayed");
///         })
///         print("after");
///     "#).unwrap();
/// }).await;
/// assert_eq!(some_var,2);
///
/// rt.idle().await
/// # }
/// ```
#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "futures")))]
#[macro_export]
#[deprecated]
macro_rules! async_with{
    ($context:expr => |$ctx:ident| { $($t:tt)* }) => {
        $crate::AsyncContext::async_with(&$context,async |$ctx| {
            $($t)*
        })
    };
}

impl DropContext for AsyncRuntime {
    unsafe fn drop_context(&self, ctx: NonNull<qjs::JSContext>) {
        //TODO
        let guard = match self.inner.try_lock() {
            Some(x) => x,
            None => {
                #[cfg(not(feature = "parallel"))]
                {
                    // `RefCell` is neither `Send` nor `Sync`, so a failed
                    // `try_borrow_mut` is always this same thread and freeing
                    // directly is safe.
                    unsafe { qjs::JS_FreeContext(ctx.as_ptr()) }
                    return;
                }
                #[cfg(feature = "parallel")]
                {
                    self.pending_free
                        .send(ctx)
                        .expect("runtime should be alive while contexts life");
                    return;
                }
            }
        };
        guard.runtime.update_stack_top();
        unsafe { qjs::JS_FreeContext(ctx.as_ptr()) }
        // Explicitly drop the guard to ensure it is valid during the entire use of runtime
        mem::drop(guard);
    }
}

/// An asynchronous single execution context with its own global variables and stack.
///
/// Can share objects with other contexts of the same runtime.
#[cfg_attr(feature = "doc-cfg", doc(cfg(feature = "futures")))]
#[derive(Clone)]
pub struct AsyncContext(pub(crate) ContextOwner<AsyncRuntime>);

impl AsyncContext {
    /// Create a async context form a raw context pointer.
    ///
    /// # Safety
    /// The context must be of the correct runtime.
    /// The context must also have valid reference count, one which can be decremented when this
    /// object is dropped without going negative.
    pub unsafe fn from_raw(ctx: NonNull<qjs::JSContext>, rt: AsyncRuntime) -> Self {
        AsyncContext(ContextOwner::new(ctx, rt))
    }

    /// Creates a base context with only the required functions registered.
    /// If additional functions are required use [`AsyncContext::custom`],
    /// [`AsyncContext::builder`] or [`AsyncContext::full`].
    pub async fn base(runtime: &AsyncRuntime) -> Result<Self> {
        Self::custom::<intrinsic::None>(runtime).await
    }

    /// Creates a context with only the required intrinsics registered.
    /// If additional functions are required use [`AsyncContext::custom`],
    /// [`AsyncContext::builder`] or [`AsyncContext::full`].
    pub async fn custom<I: Intrinsic>(runtime: &AsyncRuntime) -> Result<Self> {
        let guard = runtime.inner.lock().await;
        let ctx = NonNull::new(unsafe { qjs::JS_NewContextRaw(guard.runtime.rt.as_ptr()) })
            .ok_or(Error::Allocation)?;
        unsafe { qjs::JS_AddIntrinsicBaseObjects(ctx.as_ptr()) };
        unsafe { I::add_intrinsic(ctx) };
        let res = unsafe { ContextOwner::new(ctx, runtime.clone()) };
        guard.runtime.drain_pending_free();
        mem::drop(guard);

        Ok(AsyncContext(res))
    }

    /// Creates a context with all standard available intrinsics registered.
    /// If precise control is required of which functions are available use
    /// [`AsyncContext::custom`] or [`AsyncContext::builder`].
    pub async fn full(runtime: &AsyncRuntime) -> Result<Self> {
        let guard = runtime.inner.lock().await;
        let ctx = NonNull::new(unsafe { qjs::JS_NewContext(guard.runtime.rt.as_ptr()) })
            .ok_or(Error::Allocation)?;
        let res = unsafe { ContextOwner::new(ctx, runtime.clone()) };
        // Explicitly drop the guard to ensure it is valid during the entire use of runtime
        guard.runtime.drain_pending_free();
        mem::drop(guard);

        Ok(AsyncContext(res))
    }

    /// Create a context builder for creating a context with a specific set of intrinsics
    pub fn builder() -> ContextBuilder<()> {
        ContextBuilder::default()
    }

    /// Returns the associated runtime
    pub fn runtime(&self) -> &AsyncRuntime {
        self.0.rt()
    }

    /// A entry point for manipulating and using JavaScript objects and scripts.
    ///
    /// # Example
    ///
    /// ```
    /// # use rquickjs::{prelude::*, Function, async_with, AsyncRuntime, AsyncContext, Result};
    /// # use std::time::Duration;
    /// # async fn run(){
    /// # let rt = AsyncRuntime::new().unwrap();
    ///
    /// // In order for futures to convert to JavaScript promises they need to return `Result`.
    /// async fn delay<'js>(amount: f64, cb: Function<'js>) -> Result<()> {
    ///     tokio::time::sleep(Duration::from_secs_f64(amount)).await;
    ///     cb.call::<(), ()>(());
    ///     Ok(())
    /// }
    ///
    /// let ctx = AsyncContext::full(&rt).await.unwrap();
    /// ctx.async_with(async |ctx|{
    ///
    ///     let delay = Function::new(ctx.clone(),Async(delay))
    ///         .unwrap()
    ///         .with_name("delay")
    ///         .unwrap();
    ///
    ///     let global = ctx.globals();
    ///     global.set("delay",delay).unwrap();
    ///     ctx.eval::<(),_>(r#"
    ///         delay(1,() => {
    ///             // do something
    ///         })
    ///     "#).unwrap();
    /// }).await;
    /// # }
    /// ```
    pub fn async_with<F, R>(&self, f: F) -> WithFuture<F, R>
    where
        F: for<'js> AsyncFnOnce(Ctx<'js>) -> R + ParallelSend,
        R: ParallelSend,
    {
        WithFuture::new(self, f)
    }

    /// A entry point for manipulating and using JavaScript objects and scripts.
    ///
    /// This closure can't return a future, if you need to await JavaScript promises prefer the
    /// [`async_with`] function.
    pub async fn with<F, R>(&self, f: F) -> R
    where
        F: for<'js> FnOnce(Ctx<'js>) -> R + ParallelSend,
        R: ParallelSend,
    {
        let guard = self.0.rt().inner.lock().await;
        guard.runtime.update_stack_top();
        let ctx = unsafe { Ctx::new_async(self) };
        let res = f(ctx);
        guard.runtime.drain_pending_free();
        res
    }
}

// Since the reference to runtime is behind a Arc this object is send
#[cfg(feature = "parallel")]
unsafe impl Send for AsyncContext {}

// Since all functions lock the global runtime lock access is synchronized so
// this object is sync
#[cfg(feature = "parallel")]
unsafe impl Sync for AsyncContext {}

#[cfg(test)]
mod test {
    use crate::{AsyncContext, AsyncRuntime};

    #[tokio::test]
    async fn base_asyc_context() {
        let rt = AsyncRuntime::new().unwrap();
        let ctx = AsyncContext::builder().build_async(&rt).await.unwrap();
        ctx.async_with(async |ctx| {
            ctx.globals();
        })
        .await;
    }

    #[tokio::test]
    async fn clone_ctx() {
        let rt = AsyncRuntime::new().unwrap();
        let ctx = AsyncContext::full(&rt).await.unwrap();

        let ctx_clone = ctx.clone();

        ctx.with(|ctx| {
            let val: i32 = ctx.eval(r#"1+1"#).unwrap();

            assert_eq!(val, 2);
            println!("{:?}", ctx.globals());
        })
        .await;

        ctx_clone
            .with(|ctx| {
                let val: i32 = ctx.eval(r#"1+1"#).unwrap();

                assert_eq!(val, 2);
                println!("{:?}", ctx.globals());
            })
            .await;
    }

    #[cfg(feature = "parallel")]
    #[tokio::test]
    async fn parallel_drop() {
        use std::{
            sync::{Arc, Barrier},
            thread,
        };

        let wait_for_entry = Arc::new(Barrier::new(2));
        let wait_for_exit = Arc::new(Barrier::new(2));

        let rt = AsyncRuntime::new().unwrap();
        let ctx_1 = AsyncContext::full(&rt).await.unwrap();
        let ctx_2 = AsyncContext::full(&rt).await.unwrap();
        let wait_for_entry_c = wait_for_entry.clone();
        let wait_for_exit_c = wait_for_exit.clone();
        thread::spawn(move || {
            println!("wait_for entry ctx_1");
            wait_for_entry_c.wait();
            println!("dropping");
            std::mem::drop(ctx_1);
            println!("wait_for exit ctx_1");
            wait_for_exit_c.wait();
        });

        println!("wait_for entry ctx_2");
        rt.run_gc().await;
        ctx_2
            .with(|ctx| {
                wait_for_entry.wait();
                println!("evaling");
                let i: i32 = ctx.eval("2 + 8").unwrap();
                assert_eq!(i, 10);
                println!("wait_for exit ctx_2");
                wait_for_exit.wait();
            })
            .await;
    }
}