Struct StdSystem

pub struct StdSystem<C: CustomTypes<StdSystem<C>>> { /* private fields */ }

A type implementing the System trait which supports all features.

StdSystem can be configured with CustomTypes and Config, which together allow for the definition of any external features (e.g., defining syscalls), as well as overriding default behavior (e.g., rpc intercepting).

Implementations

impl<C: CustomTypes<StdSystem<C>>> StdSystem<C>

pub fn new_sync( base_url: CompactString, project_name: Option<&str>, config: Config<C, Self>, clock: Arc<Clock>, ) -> Self

Equivalent to StdSystem::new_async except that it can be executed outside of async context. Note that using this from within async context can result in a panic from, e.g., tokio trying to create a runtime within a runtime.

Examples found in repository

examples/basic.rs (line 132)

fn main() {
    // read in an xml file whose path is given as a command line argument
    let args = std::env::args().collect::<Vec<_>>();
    if args.len() != 2 {
        panic!("usage: {} [xml file]", &args[0]);
    }
    let mut xml = String::new();
    std::fs::File::open(&args[1]).expect("failed to open file").read_to_string(&mut xml).expect("failed to read file");

    // create a new shared clock and start a thread that updates it at our desired interval
    let clock = Arc::new(Clock::new(UtcOffset::UTC, Some(Precision::Medium)));
    let clock_clone = clock.clone();
    std::thread::spawn(move || loop {
        std::thread::sleep(CLOCK_INTERVAL);
        clock_clone.update();
    });

    // create a custom config for the system - in this simple example we just implement the say/think blocks to print to stdout
    let config = Config::<C, StdSystem<C>> {
        request: None,
        command: Some(Rc::new(|_mc, key, command, _proc| match command {
            Command::Print { style: _, value } => {
                if let Some(value) = value {
                    println!("{value:?}");
                }
                key.complete(Ok(())); // any request that you handle must be completed - otherwise the calling process will hang forever
                CommandStatus::Handled
            }
            _ => CommandStatus::UseDefault { key, command }, // anything you don't handle should return the key and command to invoke the default behavior instead
        })),
    };

    // initialize our system with all the info we've put together
    let system = Rc::new(StdSystem::new_sync(CompactString::new(BASE_URL), None, config, clock.clone()));
    let mut env = get_running_project(&xml, system);

    // begin running the code - these are some helpers to make things more efficient in terms of memory and cpu resources
    let mut idle_sleeper = IdleAction::new(YIELDS_BEFORE_SLEEP, Box::new(|| std::thread::sleep(IDLE_SLEEP_TIME)));
    let mut next_collect = clock.read(Precision::Medium) + COLLECT_INTERVAL;
    loop {
        env.mutate(|mc, env| {
            let mut proj = env.proj.borrow_mut(mc);
            for _ in 0..1024 {
                // step the virtual machine forward by one bytecode instruction
                let res = proj.step(mc);
                if let ProjectStep::Error { error, proc } = &res {
                    // if we get an error, we can generate an error summary including a stack trace - here we just print out the result
                    let trace = ErrorSummary::extract(error, proc, &env.locs);
                    println!("error: {error:?}\ntrace: {trace:?}");
                }
                // this takes care of performing thread sleep if we get a bunch of no-ops from proj.step back to back
                idle_sleeper.consume(&res);
            }
        });
        // if it's time for us to do garbage collection, do it and reset the next collection time
        if clock.read(Precision::Low) >= next_collect {
            env.collect_all();
            next_collect = clock.read(Precision::Medium) + COLLECT_INTERVAL;
        }
    }
}

pub async fn new_async( base_url: CompactString, project_name: Option<&str>, config: Config<C, Self>, clock: Arc<Clock>, ) -> Self

Initializes a new instance of StdSystem targeting the given NetsBlox server base url, e.g., https://cloud.netsblox.org.

pub async fn call_rpc_async( &self, host: Option<&str>, service: &str, rpc: &str, args: &[(&str, &Json)], ) -> Result<SimpleValue, CompactString>

Asynchronously calls an RPC and returns the result. This function directly makes requests to NetsBlox, bypassing any RPC hook defined by Config.

pub fn get_public_id(&self) -> CompactString

Gets the public id of the running system that can be used to send messages to this client.

pub fn inject_message( &self, msg_type: CompactString, values: VecMap<CompactString, SimpleValue, false>, )

Injects a message into the receiving queue as if received over the network.

Trait Implementations

impl<C: CustomTypes<StdSystem<C>>> System<C> for StdSystem<C>

type RequestKey = AsyncKey<Result<<C as CustomTypes<StdSystem<C>>>::Intermediate, CompactString>>

Key type used to await the result of an asynchronous request.

type CommandKey = AsyncKey<Result<(), CompactString>>

Key type used to await the completion of an asynchronous command.

fn rand<T: SampleUniform, R: SampleRange<T>>(&self, range: R) -> T

Gets a random value sampled from the given range, which is assumed to be non-empty. The input for this generic function is such that it is compatible with rand::Rng::gen_range, which makes it possible to implement this function with any random provider under the rand crate standard.

fn time(&self, precision: Precision) -> SysTime

Gets the current system time.

fn perform_request<'gc>( &self, mc: &Mutation<'gc>, request: Request<'gc, C, Self>, proc: &mut Process<'gc, C, Self>, ) -> Result<Self::RequestKey, ErrorCause<C, Self>>

Performs a general request which returns a value to the system. Ideally, this function should be non-blocking, and the requestor will await the result asynchronously. The Entity that made the request is provided for context.

fn poll_request<'gc>( &self, mc: &Mutation<'gc>, key: &Self::RequestKey, _proc: &mut Process<'gc, C, Self>, ) -> Result<AsyncResult<Result<Value<'gc, C, Self>, CompactString>>, ErrorCause<C, Self>>

Poll for the completion of an asynchronous request. The Entity that made the request is provided for context.

fn perform_command<'gc>( &self, mc: &Mutation<'gc>, command: Command<'gc, '_, C, Self>, proc: &mut Process<'gc, C, Self>, ) -> Result<Self::CommandKey, ErrorCause<C, Self>>

Performs a general command which does not return a value to the system. Ideally, this function should be non-blocking, and the commander will await the task’s completion asynchronously. The Entity that issued the command is provided for context.

fn poll_command<'gc>( &self, _mc: &Mutation<'gc>, key: &Self::CommandKey, _proc: &mut Process<'gc, C, Self>, ) -> Result<AsyncResult<Result<(), CompactString>>, ErrorCause<C, Self>>

Poll for the completion of an asynchronous command. The Entity that issued the command is provided for context.

fn send_message( &self, msg_type: CompactString, values: VecMap<CompactString, Json, false>, targets: Vec<CompactString>, expect_reply: bool, ) -> Result<Option<ExternReplyKey>, ErrorCause<C, StdSystem<C>>>

Sends a message containing a set of named values to each of the specified targets. The expect_reply value controls whether or not to use a reply mechanism to asynchronously receive a response from the target(s). In the case that there are multiple targets, only the first reply (if any) should be used.

fn poll_reply(&self, key: &ExternReplyKey) -> AsyncResult<Option<Json>>

Polls for a response from a client initiated by System::send_message. If the client responds, a value of [Some(x)] is returned. The system may elect to impose a timeout for reply results, in which case None is returned instead.

fn send_reply( &self, key: InternReplyKey, value: Json, ) -> Result<(), ErrorCause<C, Self>>

Sends a reply to the sender of a blocking message this client received.

fn receive_message(&self) -> Option<IncomingMessage>

Attempts to receive a message from the message buffer. This operation is always non-blocking and returns None if there are no messages in the buffer. If a message is received, a tuple of form (msg_type, values, reply_key) is returned.