Trait brane_exe::spec::VmPlugin

source · 
pub trait VmPlugin:
    'static
    + Send
    + Sync {
    type GlobalState: CustomGlobalState;
    type LocalState: CustomLocalState;
    type PreprocessError: 'static + Send + Sync + Error;
    type ExecuteError: 'static + Send + Sync + Error;
    type StdoutError: 'static + Send + Sync + Error;
    type CommitError: 'static + Send + Sync + Error;

    // Required methods
    fn preprocess<'life0, 'async_trait>(
        global: Arc<RwLock<Self::GlobalState>>,
        local: Self::LocalState,
        pc: ProgramCounter,
        loc: Location,
        name: DataName,
        preprocess: PreprocessKind,
        prof: ProfileScopeHandle<'life0>,
    ) -> Pin<Box<dyn Future<Output = Result<AccessKind, Self::PreprocessError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn execute<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        global: &'life0 Arc<RwLock<Self::GlobalState>>,
        local: &'life1 Self::LocalState,
        info: TaskInfo<'life2>,
        prof: ProfileScopeHandle<'life3>,
    ) -> Pin<Box<dyn Future<Output = Result<Option<FullValue>, Self::ExecuteError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait;
    fn stdout<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        global: &'life0 Arc<RwLock<Self::GlobalState>>,
        local: &'life1 Self::LocalState,
        text: &'life2 str,
        newline: bool,
        prof: ProfileScopeHandle<'life3>,
    ) -> Pin<Box<dyn Future<Output = Result<(), Self::StdoutError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait;
    fn publicize<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>(
        global: &'life0 Arc<RwLock<Self::GlobalState>>,
        local: &'life1 Self::LocalState,
        loc: &'life2 Location,
        name: &'life3 str,
        path: &'life4 Path,
        prof: ProfileScopeHandle<'life5>,
    ) -> Pin<Box<dyn Future<Output = Result<(), Self::CommitError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait,
             'life5: 'async_trait;
    fn commit<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'async_trait>(
        global: &'life0 Arc<RwLock<Self::GlobalState>>,
        local: &'life1 Self::LocalState,
        loc: &'life2 Location,
        name: &'life3 str,
        path: &'life4 Path,
        data_name: &'life5 str,
        prof: ProfileScopeHandle<'life6>,
    ) -> Pin<Box<dyn Future<Output = Result<(), Self::CommitError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait,
             'life5: 'async_trait,
             'life6: 'async_trait;
}
Expand description

A trait that implements various missing pieces in task execution. See the brane-tsk crate for implementations.

Required Associated Types§

source

type GlobalState: CustomGlobalState

The type of the custom, App-wide, global state.

source

type LocalState: CustomLocalState

The type of the custom, thread-local, local state.

source

type PreprocessError: 'static + Send + Sync + Error

The error type of the preprocess function.

source

type ExecuteError: 'static + Send + Sync + Error

The error type of the execute function.

source

type StdoutError: 'static + Send + Sync + Error

The error type of the stdout function.

source

type CommitError: 'static + Send + Sync + Error

The error type of the publicize and commit functions.

Required Methods§

source

fn preprocess<'life0, 'async_trait>( global: Arc<RwLock<Self::GlobalState>>, local: Self::LocalState, pc: ProgramCounter, loc: Location, name: DataName, preprocess: PreprocessKind, prof: ProfileScopeHandle<'life0>, ) -> Pin<Box<dyn Future<Output = Result<AccessKind, Self::PreprocessError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

A function that preprocesses a given dataset in the given way. Typically, this involves “transferring data” as a preprocessing step.

§Generic arguments
  • E: The kind of error this function returns. Should, of course, implement Error.
§Arguments
  • global: The custom global state for keeping track of your own things during execution.
  • local: The custom local state for keeping track of your own things faster but only local to this (execution) thread.
  • pc: A ProgramCounter that denotes for which task in the workflow we’re preprocessing.
  • loc: The location where this preprocessing should happen.
  • name: The name of the intermediate result to make public. You’ll typically only use this for debugging.
  • preprocess: The PreprocessKind that determines what you must do to make the dataset available.
  • prof: A ProfileScopeHandle that can be used to prove additional details about the timings of this function.
§Returns

This function should return an AccessKind which describes how to access the preprocessed data.

It is expected that the preprocessed data is available the moment the function returns.

§Errors

This function may error whenever it likes.

source

fn execute<'life0, 'life1, 'life2, 'life3, 'async_trait>( global: &'life0 Arc<RwLock<Self::GlobalState>>, local: &'life1 Self::LocalState, info: TaskInfo<'life2>, prof: ProfileScopeHandle<'life3>, ) -> Pin<Box<dyn Future<Output = Result<Option<FullValue>, Self::ExecuteError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

A function that executes the given task.

§Generic arguments
  • E: The kind of error this function returns. Should, of course, implement Error.
§Arguments
  • global: The custom global state for keeping track of your own things during execution.
  • local: The custom local state for keeping track of your own things faster but only local to this (execution) thread.
  • info: A TaskInfo that contains all the information about the to-be-executed task the VM provides you with. Note: You have to preprocess the arguments contained within. Be aware that the path describes by the IntermediateResults is relative to some directory you still have to prepend.
  • prof: A ProfileScopeHandle that can be used to prove additional details about the timings of this function.
§Returns

This function should return either a FullValue, or None (where None is equivalent to FullValue::Void).

§Errors

This function may error whenever it likes.

source

fn stdout<'life0, 'life1, 'life2, 'life3, 'async_trait>( global: &'life0 Arc<RwLock<Self::GlobalState>>, local: &'life1 Self::LocalState, text: &'life2 str, newline: bool, prof: ProfileScopeHandle<'life3>, ) -> Pin<Box<dyn Future<Output = Result<(), Self::StdoutError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

A function that prints a message to stdout - whatever that may be.

This function is called whenever BraneScript’s print or println are called.

§Generic arguments
  • E: The kind of error this function returns. Should, of course, implement Error.
§Arguments
  • global: The custom global state for keeping track of your own things during execution.
  • local: The custom local state for keeping track of your own things faster but only local to this (execution) thread.
  • text: The text to write to your version of stdout.
  • newline: Whether or not to print a closing newline after the text (i.e., whether to use println or print).
  • prof: A ProfileScopeHandle that can be used to prove additional details about the timings of this function.
§Errors

This function may error whenever it likes.

source

fn publicize<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( global: &'life0 Arc<RwLock<Self::GlobalState>>, local: &'life1 Self::LocalState, loc: &'life2 Location, name: &'life3 str, path: &'life4 Path, prof: ProfileScopeHandle<'life5>, ) -> Pin<Box<dyn Future<Output = Result<(), Self::CommitError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait,

A function that “publicizes” the given intermediate result.

This is not really commiting, as it is making the intermediate dataset available upon request. In a distributed/instance setting, this typically means making the registry aware of it.

§Generic arguments
  • E: The kind of error this function returns. Should, of course, implement Error.
§Arguments
  • global: The custom global state for keeping track of your own things during execution.
  • local: The custom local state for keeping track of your own things faster but only local to this (execution) thread.
  • loc: The location where the dataset currently lives.
  • name: The name of the intermediate result to make public.
  • path: The path where the intermediate result is available. You’ll probably want to archive this before continuing. Note: Be aware that this path is relative to some directory you still have to prepend.
  • prof: A ProfileScopeHandle that can be used to prove additional details about the timings of this function.
§Errors

This function may error whenever it likes.

source

fn commit<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'async_trait>( global: &'life0 Arc<RwLock<Self::GlobalState>>, local: &'life1 Self::LocalState, loc: &'life2 Location, name: &'life3 str, path: &'life4 Path, data_name: &'life5 str, prof: ProfileScopeHandle<'life6>, ) -> Pin<Box<dyn Future<Output = Result<(), Self::CommitError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, 'life6: 'async_trait,

A function that commits the given intermediate result by promoting it a Data.

Typically, this involves saving the data somewhere outside of the results folder and then updating the registry on its existance.

§Generic arguments
  • E: The kind of error this function returns. Should, of course, implement Error.
§Arguments
  • global: The custom global state for keeping track of your own things during execution.
  • local: The custom local state for keeping track of your own things faster but only local to this (execution) thread.
  • loc: The location where the dataset currently lives.
  • name: The name of the intermediate result to promoto (you’ll typically use this for debugging only).
  • path: The path where the intermediate result is available. You’ll probably want to archive this somewhere else before continuing. Note: Be aware that this path is relative to some directory you still have to prepend.
  • data_name: The identifier of the dataset once the intermediate result is promoted. If it already exists, you’ll probably want to override the old value with the new one.
  • prof: A ProfileScopeHandle that can be used to prove additional details about the timings of this function.
§Errors

This function may error whenever it likes.

Object Safety§

This trait is not object safe.

Implementors§