diff --git a/fj-host/src/lib.rs b/fj-host/src/lib.rs index acba8d608..4a8f87f53 100644 --- a/fj-host/src/lib.rs +++ b/fj-host/src/lib.rs @@ -1,3 +1,10 @@ +//! Plugin host for Fornjot models +//! +//! Fornjot models are loaded into the Fornjot application as plugins. This +//! crate contains the code required to host plugins. + +#![deny(missing_docs)] + use std::{ collections::{HashMap, HashSet}, ffi::OsStr, @@ -11,6 +18,7 @@ use std::{ use notify::Watcher as _; use thiserror::Error; +/// Represents a Fornjot model pub struct Model { src_path: PathBuf, lib_path: PathBuf, @@ -18,6 +26,11 @@ pub struct Model { } impl Model { + /// Initialize the model from a path + /// + /// Optionally, the target directory where plugin files are compiled to can + /// be provided. If it is not provided, the target directory is assumed to + /// be located within the model path. pub fn from_path( path: PathBuf, target_dir: Option, @@ -56,6 +69,13 @@ impl Model { }) } + /// Load the model once + /// + /// The passed arguments are provided to the model. Returns the shape that + /// the model returns. + /// + /// Please refer to [`Model::load_and_watch`], if you want to watch the + /// model for changes, reloading it continually. pub fn load_once( &self, arguments: &HashMap, @@ -96,6 +116,12 @@ impl Model { Ok(shape) } + /// Load the model, then watch it for changes + /// + /// Whenever a change is detected, the model is being reloaded. + /// + /// Consumes this instance of `Model` and returns a [`Watcher`], which can + /// be queried for changes to the model. pub fn load_and_watch( self, parameters: HashMap, @@ -175,6 +201,7 @@ impl Model { } } +/// Watches a model for changes, reloading it continually pub struct Watcher { _watcher: Box, channel: mpsc::Receiver<()>, @@ -183,6 +210,10 @@ pub struct Watcher { } impl Watcher { + /// Receive an updated shape that the reloaded model created + /// + /// Returns `None`, if the model has not changed since the last time this + /// method was called. pub fn receive(&self) -> Option { match self.channel.try_recv() { Ok(()) => { @@ -216,17 +247,22 @@ impl Watcher { } } +/// An error that can occur when loading or reloading a model #[derive(Debug, Error)] pub enum Error { + /// Model failed to compile #[error("Error compiling model")] Compile, + /// I/O error while loading the model #[error("I/O error while loading model")] Io(#[from] io::Error), + /// Failed to load the model's dynamic library #[error("Error loading model from dynamic library")] LibLoading(#[from] libloading::Error), + /// Error while watching the model code for changes #[error("Error watching model for changes")] Notify(#[from] notify::Error), }