Skip to main content

Object Run

obj.run() runs every function and field tagged #[run] on an object, in order. It turns an object into a workflow: a list of steps that live with the data they work on, and that you can reorder, extend, or send somewhere else like any other data.

Steps​

Every #[run] function and field on the object runs when you call run(), in the order they're written:

basic-run.stofPlayground ↗
Workflow: {
  out: []

  #[run]
  fn step_one() { self.out.push_back('one'); }

  #[run]
  fn step_two() { self.out.push_back('two'); }
}

#[main]
fn main() {
  self.Workflow.run();
  pln(self.Workflow.out);
}
Output

Ordering Steps​

A number moves a step. Unnumbered steps count as 0, so #[run(-1)] runs before them and #[run(1)] after, and steps with the same number keep the order they're written in:

ordering.stofPlayground ↗
Workflow: {
  out: []

  #[run(1)]
  fn cleanup() { self.out.push_back('cleanup'); }

  #[run]
  fn work() { self.out.push_back('work'); }

  #[run(-1)]
  fn setup() { self.out.push_back('setup'); }
}

#[main]
fn main() {
  self.Workflow.run();
  pln(self.Workflow.out);
}
Output

Steps That Are Objects​

A child object tagged #[run] runs its own steps, so each stage of a workflow can be an object with its own data:

nested.stofPlayground ↗
Workflow: {
  #[run]
  step_one: {
      #[run]
      fn execute() { pln('step 1'); }
  }

  #[run]
  step_two: {
      #[run]
      fn execute() { pln('step 2'); }
  }
}

#[main]
fn main() {
  self.Workflow.run();
}
Output

Steps From a Type​

A type can define steps for every instance. run() on an instance runs the type's steps on that instance, then any new steps the instance adds:

type-steps.stofPlayground ↗
#[type]
Onboarding: {
  str email: ''
  list log: []

  #[run]
  fn check() { self.log.push_back('checked ' + self.email); }

  #[run]
  fn welcome() { self.log.push_back('welcome email'); }
}

Onboarding team: {
  email: 'team@example.com'

  #[run]
  fn invite() { self.log.push_back('invited the team'); }
}

#[main]
fn main() {
  self.team.run();
  pln(self.team.log);
}
Output

Every step has a name: its field or function name. An instance step with the same name as a type step replaces it, in the same place, so each step runs once. A null field removes a type's step, and #[run({'name': 'check'})] lets a step with a different name replace check:

overrides.stofPlayground ↗
#[type]
Onboarding: {
  list log: []

  #[run]
  fn check() { self.log.push_back('check'); }

  #[run]
  fn welcome() { self.log.push_back('welcome email'); }

  #[run]
  fn finish() { self.log.push_back('finish'); }
}

Onboarding quiet: {
  #[run]
  welcome: null

  #[run({'name': 'check'})]
  fn strict_check() { self.log.push_back('strict check'); }
}

#[main]
fn main() {
  self.quiet.run();
  pln(self.quiet.log);
}
Output

Numbers work the same way across the type and the instance, so an instance can put a step anywhere: #[run(-1)] runs before the type's unnumbered steps.

Choosing Steps​

run() takes two options. prototype picks which steps run: 'first' (the default: the type's steps, then the instance's new ones), 'last' (the instance's new steps first), 'none' (only the steps on the instance itself), or 'only' (only the type's steps). steps runs just the named steps, in that order:

choosing.stofPlayground ↗
#[type]
Report: {
  list log: []

  #[run]
  fn load() { self.log.push_back('load'); }

  #[run]
  fn summarize() { self.log.push_back('summarize'); }

  #[run]
  fn send() { self.log.push_back('send'); }
}

#[main]
fn main() {
  const report = new Report {};
  report.run(steps = ['load', 'summarize']);
  pln(report.log);
}
Output

An object can set these for itself with its own attribute, like #[run({'prototype': 'none'})] or #[run({'steps': ['load', 'send']})].

Passing Arguments​

#[run({'args': [...]})] passes arguments to a step:

args.stofPlayground ↗
Workflow: {
  #[run({'args': [42]})]
  fn setup(val: int) {
      self.configured = val;
  }
}

#[main]
fn main() {
  self.Workflow.run();
  pln(self.Workflow.configured);
}
Output

A List of Steps​

#[run] on a list runs every item in it: functions, and objects with their own steps:

list-run.stofPlayground ↗
Workflow: {
  done: false
  sub_done: false

  #[run]
  steps: [
      () => { self.done = true; },
      { #[run] fn inner() { super.sub_done = true; } }
  ]
}

#[main]
fn main() {
  self.Workflow.run();
  pln(self.Workflow.done);
  pln(self.Workflow.sub_done);
}
Output

A Realistic Shape​

The pattern these build toward is a task that knows how to do its own work: fetch something, check what comes back, and record the result:

#[type]
Task: {
ok: false
result: null
endpoint: 'https://api.example.com/rates'

#[run]
fn fetch() {
const response = await Http::fetch(self.endpoint);
self.result = Http::parse(response, new {});
}

#[run]
fn check() {
self.ok = <Rates>.schemafy(self.result);
}
}

This one doesn't run on this site, since it needs network access (see Http). Whatever a task does inside, it runs the same way: task.run().

Async Steps​

run() runs steps one after another, and an async fn step is awaited: it finishes before the next step starts.

async-step.stofPlayground ↗
Workflow: {
  out: []

  #[run(1)]
  async fn fetch() {
      sleep(10ms);
      self.out.push_back('fetched');
  }

  #[run(2)]
  fn report() { self.out.push_back('reported'); }
}

#[main]
fn main() {
  self.Workflow.run();
  pln(self.Workflow.out);
}
Output

To run async work side by side instead, start it from a step, collect the promises, and await them in a later step. See Async for how that works:

async-run.stofPlayground ↗
#[type]
/// Setup a type that handles async the way you'd like.
/// Common to put helpers in a Job type that can resolve to the Workflow parent, etc.
Workflow: {
  list jobs: []
  list handles: []

  #[run(1)]
  fn run_jobs() {
      for (const job in self.jobs) {
          // in real-life I'd switch on type and add fn (async gets pushed to handles, etc.)
          if (job.parent() != self) job.move(self);
          job.run();
      }
  }

  #[run(2)]
  fn await_handles() {
      pln(`awaiting ${self.handles.len()} handles`);
      await self.handles;
      self.handles = []; // reset handles for any #[run(3)] and beyond
  }
}

#[type]
Job: {
  text: 'default'
  #[run] fn running() { pln(self.text); }
}

#[type]
AsyncJob: {
  #[run]
  fn running() {
      const handles = super.handles ?? [];
      handles.push_back(async { sleep(10ms); pln('Running an Async Job!'); });
  }
}

#[main]
fn main() {
  const flow = new Workflow {};
  flow.jobs.push_back(new Job { text: 'First Job' });
  flow.jobs.push_back(new AsyncJob {});
  flow.run();
  pln('Done Running');
}
Output

Next, Import & Export.