Struct nu_protocol::engine::EngineState

pub struct EngineState {
    pub scope: Vec<ScopeFrame>,
    pub ctrlc: Option<Arc<AtomicBool>>,
    pub env_vars: HashMap<String, Value>,
    /* private fields */
}

The core global engine state. This includes all global definitions as well as any global state that will persist for the whole session.

Declarations, variables, blocks, and other forms of data are held in the global state and referenced elsewhere using their IDs. These IDs are simply their index into the global state. This allows us to more easily handle creating blocks, binding variables and callsites, and more, because each of these will refer to the corresponding IDs rather than their definitions directly. At runtime, this means less copying and smaller structures.

Note that the runtime stack is not part of this global state. Runtime stacks are handled differently, but they also rely on using IDs rather than full definitions.

A note on implementation:

Much of the global definitions are built on the Bodil’s ‘im’ crate. This gives us a way of working with lists of definitions in a way that is very cheap to access, while also allowing us to update them at key points in time (often, the transition between parsing and evaluation).

Over the last two years we tried a few different approaches to global state like this. I’ll list them here for posterity, so we can more easily know how we got here:

• Rc - Rc is cheap, but not thread-safe. The moment we wanted to work with external processes, we needed a way send to stdin/stdout. In Rust, the current practice is to spawn a thread to handle both. These threads would need access to the global state, as they’ll need to process data as it streams out of the data pipeline. Because Rc isn’t thread-safe, this breaks.

• Arc - Arc is the thread-safe version of the above. Often Arc is used in combination with a Mutex or RwLock, but you can use Arc by itself. We did this a few places in the original Nushell. This can work but because of Arc’s nature of not allowing mutation if there’s a second copy of the Arc around, this ultimately becomes limiting.

• Arc + Mutex/RwLock - the standard practice for thread-safe containers. Unfortunately, this would have meant we would incur a lock penalty every time we needed to access any declaration or block. As we would be reading far more often than writing, it made sense to explore solutions that favor large amounts of reads.

• im - the im crate was ultimately chosen because it has some very nice properties: it gives the ability to cheaply clone these structures, which is nice as EngineState may need to be cloned a fair bit to follow ownership rules for closures and iterators. It also is cheap to access. Favoring reads here fits more closely to what we need with Nushell. And, of course, it’s still thread-safe, so we get the same benefits as above.

Fields

scope: Vec<ScopeFrame>

ctrlc: Option<Arc<AtomicBool>>

env_vars: HashMap<String, Value>

Implementations

impl EngineState

pub fn new() -> Self

pub fn merge_delta(
    &mut self,
    delta: StateDelta,
    stack: Option<&mut Stack>,
    cwd: impl AsRef<Path>
) -> Result<(), ShellError>

Merges a StateDelta onto the current state. These deltas come from a system, like the parser, that creates a new set of definitions and visible symbols in the current scope. We make this transactional as there are times when we want to run the parser and immediately throw away the results (namely: syntax highlighting and completions).

When we want to preserve what the parser has created, we can take its output (the StateDelta) and use this function to merge it into the global state.

pub fn num_files(&self) -> usize

pub fn num_vars(&self) -> usize

pub fn num_decls(&self) -> usize

pub fn num_aliases(&self) -> usize

pub fn num_blocks(&self) -> usize

pub fn num_overlays(&self) -> usize

pub fn print_vars(&self)

pub fn print_decls(&self)

pub fn print_blocks(&self)

pub fn print_contents(&self)

pub fn find_decl(&self, name: &[u8]) -> Option<DeclId>

pub fn find_alias(&self, name: &[u8]) -> Option<AliasId>

pub fn find_overlay(&self, name: &[u8]) -> Option<OverlayId>

pub fn find_commands_by_prefix(
    &self,
    name: &[u8]
) -> Vec<(Vec<u8>, Option<String>)>

pub fn find_aliases_by_prefix(&self, name: &[u8]) -> Vec<Vec<u8>>

pub fn get_span_contents(&self, span: &Span) -> &[u8]

pub fn get_var(&self, var_id: VarId) -> &Variable

pub fn get_decl(&self, decl_id: DeclId) -> &Box<dyn Command>

pub fn get_alias(&self, alias_id: AliasId) -> &[Span]

pub fn get_decl_ids_sorted(
    &self,
    include_hidden: bool
) -> impl Iterator<Item = DeclId>

Get all IDs of all commands within scope, sorted by the commads’ names

pub fn get_signatures(&self, include_hidden: bool) -> Vec<Signature>

Get signatures of all commands within scope.

pub fn get_signatures_with_examples(
    &self,
    include_hidden: bool
) -> Vec<(Signature, Vec<Example>, bool, bool)>

Get signatures of all commands within scope.

In addition to signatures, it returns whether each command is: a) a plugin b) custom

pub fn get_block(&self, block_id: BlockId) -> &Block

pub fn get_overlay(&self, overlay_id: OverlayId) -> &Overlay

pub fn next_span_start(&self) -> usize

pub fn files(&self) -> impl Iterator<Item = &(String, usize, usize)>

pub fn get_filename(&self, file_id: usize) -> String

pub fn get_file_source(&self, file_id: usize) -> String

pub fn add_file(&mut self, filename: String, contents: Vec<u8>) -> usize

Trait Implementations

impl Clone for EngineState

fn clone(&self) -> EngineState

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for EngineState

fn default() -> Self

Returns the “default value” for a type.