Struct AsyncTaskObject

pub struct AsyncTaskObject(/* private fields */);

Handle to a Wolfram Language AsynchronousTaskObject_WL instance.

Use spawn_with_thread() to spawn a new asynchronous task.

Implementations

impl AsyncTaskObject

pub fn spawn_with_thread<F>(f: F) -> Self

where F: FnMut(AsyncTaskObject) + Send + UnwindSafe + 'static,

Spawn a new Wolfram Language asynchronous task.

This method can be used within a LibraryLink function that was called via

Internal`CreateAsynchronousTask[
    _LibraryFunction,
    args_List,
    handler
]

to create a new AsynchronousTaskObject_WL that uses a background thread that can generate events that will be processed asynchronously by the Wolfram Language.

The background thread is given an AsyncTaskObject that has the same id as the AsyncTaskObject returned from this function. Events generated by the background thread using raise_async_event() will result in an asynchronous call to the Wolfram Language handler function specified in the call to Internal`CreateAsynchronousEvent.

Examples found in repository

examples/async/async_file_watcher.rs (lines 21-23)

fn start_file_watcher(pause_interval_ms: mint, path: String) -> mint {
    let pause_interval_ms =
        u64::try_from(pause_interval_ms).expect("mint interval overflows u64");

    let path = PathBuf::from(path);

    // Spawn a new thread, which will run in the background and check for file
    // modifications.
    let task = AsyncTaskObject::spawn_with_thread(move |task: AsyncTaskObject| {
        file_watch_thread_function(task, pause_interval_ms, &path);
    });

    task.id()
}

pub fn id(&self) -> mint

Returns the numeric ID which identifies this async object.

Examples found in repository

examples/async/async_file_watcher.rs (line 25)

fn start_file_watcher(pause_interval_ms: mint, path: String) -> mint {
    let pause_interval_ms =
        u64::try_from(pause_interval_ms).expect("mint interval overflows u64");

    let path = PathBuf::from(path);

    // Spawn a new thread, which will run in the background and check for file
    // modifications.
    let task = AsyncTaskObject::spawn_with_thread(move |task: AsyncTaskObject| {
        file_watch_thread_function(task, pause_interval_ms, &path);
    });

    task.id()
}

pub fn is_alive(&self) -> bool

Returns whether this async task is still alive.

LibraryLink C Function: asynchronousTaskAliveQ.

Examples found in repository

examples/async/async_file_watcher.rs (line 78)

fn file_watch_thread_function(
    task: AsyncTaskObject,
    pause_interval_ms: u64,
    path: &PathBuf,
) {
    let mut prev_changed: Option<SystemTime> = fs::metadata(path)
        .and_then(|metadata| metadata.modified())
        .ok();

    // Stateful closure which checks if the file at `path` has been modified since the
    // last time this closure was called (and `prev_changed was updated). Using a closure
    // simplifies the control flow in the main `loop` below, which should sleep on every
    // iteration regardless of how this function returns.
    let mut check_for_modification = || -> Option<_> {
        let changed: Option<fs::Metadata> = fs::metadata(path).ok();

        let notify: Option<SystemTime> = match (&prev_changed, changed) {
            (Some(prev), Some(latest)) => {
                let latest: SystemTime = match latest.modified() {
                    Ok(latest) => latest,
                    Err(_) => return None,
                };

                if *prev != latest {
                    prev_changed = Some(latest.clone());
                    Some(latest)
                } else {
                    None
                }
            },
            // TODO: Notify on file removal?
            (Some(_prev), None) => None,
            (None, Some(latest)) => latest.modified().ok(),
            (None, None) => None,
        };

        let time = notify?;

        let since_epoch = match time.duration_since(std::time::UNIX_EPOCH) {
            Ok(duration) => duration,
            Err(_) => return None,
        };

        let since_epoch = since_epoch.as_secs();

        Some(since_epoch)
    };

    loop {
        if !task.is_alive() {
            break;
        }

        // Check to see if the file has been modified. If it has, raise an async event
        // called "change", and attach the modification timestamp as event data.
        if let Some(modification) = check_for_modification() {
            let mut data = DataStore::new();
            data.add_i64(modification as i64);

            task.raise_async_event("change", data);
        }

        // Wait for a bit before polling again for any changes to the file.
        std::thread::sleep(Duration::from_millis(pause_interval_ms));
    }
}

pub fn is_started(&self) -> bool

Returns whether this async task has been started.

LibraryLink C Function: asynchronousTaskStartedQ.

pub fn raise_async_event(&self, name: &str, data: DataStore)

Raise a new named asynchronous event associated with the current async task.

Example

Raise a new asynchronous event with no associated data:

This will cause the Wolfram Language event handler associated with this task to be run.

LibraryLink C Function: raiseAsyncEvent.

use wolfram_library_link::{AsyncTaskObject, DataStore};

let task_object: AsyncTaskObject = todo!();

task_object.raise_async_event("change", DataStore::new());

Examples found in repository

examples/async/async_file_watcher.rs (line 88)

fn file_watch_thread_function(
    task: AsyncTaskObject,
    pause_interval_ms: u64,
    path: &PathBuf,
) {
    let mut prev_changed: Option<SystemTime> = fs::metadata(path)
        .and_then(|metadata| metadata.modified())
        .ok();

    // Stateful closure which checks if the file at `path` has been modified since the
    // last time this closure was called (and `prev_changed was updated). Using a closure
    // simplifies the control flow in the main `loop` below, which should sleep on every
    // iteration regardless of how this function returns.
    let mut check_for_modification = || -> Option<_> {
        let changed: Option<fs::Metadata> = fs::metadata(path).ok();

        let notify: Option<SystemTime> = match (&prev_changed, changed) {
            (Some(prev), Some(latest)) => {
                let latest: SystemTime = match latest.modified() {
                    Ok(latest) => latest,
                    Err(_) => return None,
                };

                if *prev != latest {
                    prev_changed = Some(latest.clone());
                    Some(latest)
                } else {
                    None
                }
            },
            // TODO: Notify on file removal?
            (Some(_prev), None) => None,
            (None, Some(latest)) => latest.modified().ok(),
            (None, None) => None,
        };

        let time = notify?;

        let since_epoch = match time.duration_since(std::time::UNIX_EPOCH) {
            Ok(duration) => duration,
            Err(_) => return None,
        };

        let since_epoch = since_epoch.as_secs();

        Some(since_epoch)
    };

    loop {
        if !task.is_alive() {
            break;
        }

        // Check to see if the file has been modified. If it has, raise an async event
        // called "change", and attach the modification timestamp as event data.
        if let Some(modification) = check_for_modification() {
            let mut data = DataStore::new();
            data.add_i64(modification as i64);

            task.raise_async_event("change", data);
        }

        // Wait for a bit before polling again for any changes to the file.
        std::thread::sleep(Duration::from_millis(pause_interval_ms));
    }
}

Trait Implementations

impl Debug for AsyncTaskObject

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.