Struct nu_protocol::engine::EngineState
source · pub struct EngineState {Show 14 fields
pub scope: ScopeFrame,
pub ctrlc: Option<Arc<AtomicBool>>,
pub env_vars: EnvVars,
pub previous_env_vars: HashMap<String, Value>,
pub config: Config,
pub pipeline_externals_state: Arc<(AtomicU32, AtomicU32)>,
pub repl_state: Arc<Mutex<ReplState>>,
pub table_decl_id: Option<usize>,
pub plugin_signatures: Option<PathBuf>,
pub history_enabled: bool,
pub history_session_id: i64,
pub regex_cache: Arc<Mutex<LruCache<String, Regex>>>,
pub is_interactive: bool,
pub is_login: bool,
/* private fields */
}
Expand description
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
- theim
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: ScopeFrame
§ctrlc: Option<Arc<AtomicBool>>
§env_vars: EnvVars
§previous_env_vars: HashMap<String, Value>
§config: Config
§pipeline_externals_state: Arc<(AtomicU32, AtomicU32)>
§repl_state: Arc<Mutex<ReplState>>
§table_decl_id: Option<usize>
§plugin_signatures: Option<PathBuf>
§history_enabled: bool
§history_session_id: i64
§regex_cache: Arc<Mutex<LruCache<String, Regex>>>
§is_interactive: bool
§is_login: bool
Implementations§
source§impl EngineState
impl EngineState
pub fn new() -> Self
sourcepub fn merge_delta(&mut self, delta: StateDelta) -> Result<(), ShellError>
pub fn merge_delta(&mut self, delta: StateDelta) -> 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.
sourcepub fn merge_env(
&mut self,
stack: &mut Stack,
cwd: impl AsRef<Path>
) -> Result<(), ShellError>
pub fn merge_env( &mut self, stack: &mut Stack, cwd: impl AsRef<Path> ) -> Result<(), ShellError>
Merge the environment from the runtime Stack into the engine state
sourcepub fn start_in_file(&mut self, file_path: Option<&str>)
pub fn start_in_file(&mut self, file_path: Option<&str>)
Mark a starting point if it is a script (e.g., nu spam.nu)
pub fn has_overlay(&self, name: &[u8]) -> bool
pub fn active_overlay_ids<'a, 'b>(
&'b self,
removed_overlays: &'a [Vec<u8>]
) -> impl DoubleEndedIterator<Item = &OverlayId> + 'awhere
'b: 'a,
pub fn active_overlays<'a, 'b>(
&'b self,
removed_overlays: &'a [Vec<u8>]
) -> impl DoubleEndedIterator<Item = &OverlayFrame> + 'awhere
'b: 'a,
pub fn active_overlay_names<'a, 'b>(
&'b self,
removed_overlays: &'a [Vec<u8>]
) -> impl DoubleEndedIterator<Item = &[u8]> + 'awhere
'b: 'a,
sourcepub fn translate_overlay_ids(&self, other: &ScopeFrame) -> Vec<OverlayId>
pub fn translate_overlay_ids(&self, other: &ScopeFrame) -> Vec<OverlayId>
Translate overlay IDs from other to IDs in self
pub fn last_overlay_name(&self, removed_overlays: &[Vec<u8>]) -> &[u8] ⓘ
pub fn last_overlay(&self, removed_overlays: &[Vec<u8>]) -> &OverlayFrame
pub fn get_overlay_name(&self, overlay_id: OverlayId) -> &[u8] ⓘ
pub fn get_overlay(&self, overlay_id: OverlayId) -> &OverlayFrame
pub fn render_env_vars(&self) -> HashMap<&String, &Value>
pub fn add_env_var(&mut self, name: String, val: Value)
pub fn get_env_var(&self, name: &str) -> Option<&Value>
pub fn get_path_env_var(&self) -> Option<&Value>
pub fn update_plugin_file(&self) -> Result<(), ShellError>
pub fn num_files(&self) -> usize
pub fn num_virtual_paths(&self) -> usize
pub fn num_vars(&self) -> usize
pub fn num_decls(&self) -> usize
pub fn num_blocks(&self) -> usize
pub fn num_modules(&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], removed_overlays: &[Vec<u8>] ) -> Option<DeclId>
pub fn find_decl_name( &self, decl_id: DeclId, removed_overlays: &[Vec<u8>] ) -> Option<&[u8]>
pub fn get_module_comments(&self, module_id: ModuleId) -> Option<&[Span]>
pub fn plugin_decls(&self) -> impl Iterator<Item = &Box<dyn Command + 'static>>
pub fn find_module( &self, name: &[u8], removed_overlays: &[Vec<u8>] ) -> Option<ModuleId>
pub fn which_module_has_decl( &self, decl_name: &[u8], removed_overlays: &[Vec<u8>] ) -> Option<&[u8]>
pub fn find_overlay(&self, name: &[u8]) -> Option<OverlayId>
pub fn find_active_overlay(&self, name: &[u8]) -> Option<OverlayId>
pub fn find_commands_by_predicate( &self, predicate: impl Fn(&[u8]) -> bool, ignore_deprecated: bool ) -> Vec<(Vec<u8>, Option<String>)>
pub fn get_span_contents(&self, span: Span) -> &[u8] ⓘ
pub fn get_config(&self) -> &Config
pub fn set_config(&mut self, conf: Config)
sourcepub fn get_plugin_config(&self, plugin: &str) -> Option<&Value>
pub fn get_plugin_config(&self, plugin: &str) -> Option<&Value>
Fetch the configuration for a plugin
The plugin
must match the registered name of a plugin. For register nu_plugin_example
the plugin name to use will be "example"
sourcepub fn history_config(&self) -> Option<HistoryConfig>
pub fn history_config(&self) -> Option<HistoryConfig>
Returns the configuration settings for command history or None
if history is disabled
pub fn get_var(&self, var_id: VarId) -> &Variable
pub fn get_constant(&self, var_id: VarId) -> Option<&Value>
pub fn set_variable_const_val(&mut self, var_id: VarId, val: Value)
pub fn get_decl(&self, decl_id: DeclId) -> &Box<dyn Command>
sourcepub fn get_decls_sorted(
&self,
include_hidden: bool
) -> impl Iterator<Item = (Vec<u8>, DeclId)>
pub fn get_decls_sorted( &self, include_hidden: bool ) -> impl Iterator<Item = (Vec<u8>, DeclId)>
Get all commands within scope, sorted by the commands’ names
pub fn get_signature(&self, decl: &Box<dyn Command>) -> Signature
sourcepub fn get_signatures(&self, include_hidden: bool) -> Vec<Signature>
pub fn get_signatures(&self, include_hidden: bool) -> Vec<Signature>
Get signatures of all commands within scope.
sourcepub fn get_signatures_with_examples(
&self,
include_hidden: bool
) -> Vec<(Signature, Vec<Example<'_>>, bool, bool, bool)>
pub fn get_signatures_with_examples( &self, include_hidden: bool ) -> Vec<(Signature, Vec<Example<'_>>, bool, 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_module(&self, module_id: ModuleId) -> &Module
pub fn get_virtual_path( &self, virtual_path_id: VirtualPathId ) -> &(String, VirtualPath)
pub fn next_span_start(&self) -> usize
pub fn files(&self) -> impl Iterator<Item = &(String, usize, usize)>
pub fn add_file(&mut self, filename: String, contents: Vec<u8>) -> usize
pub fn get_cwd(&self) -> Option<String>
pub fn set_config_path(&mut self, key: &str, val: PathBuf)
pub fn get_config_path(&self, key: &str) -> Option<&PathBuf>
pub fn build_usage(&self, spans: &[Span]) -> (String, String)
pub fn build_module_usage( &self, module_id: ModuleId ) -> Option<(String, String)>
pub fn current_work_dir(&self) -> String
pub fn get_file_contents(&self) -> &[(Vec<u8>, usize, usize)]
pub fn get_startup_time(&self) -> i64
pub fn set_startup_time(&mut self, startup_time: i64)
Trait Implementations§
source§impl Clone for EngineState
impl Clone for EngineState
source§fn clone(&self) -> EngineState
fn clone(&self) -> EngineState
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreAuto Trait Implementations§
impl !RefUnwindSafe for EngineState
impl Send for EngineState
impl Sync for EngineState
impl Unpin for EngineState
impl !UnwindSafe for EngineState
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<D> OwoColorize for D
impl<D> OwoColorize for D
§fn fg<C>(&self) -> FgColorDisplay<'_, C, Self>where
C: Color,
fn fg<C>(&self) -> FgColorDisplay<'_, C, Self>where
C: Color,
§fn bg<C>(&self) -> BgColorDisplay<'_, C, Self>where
C: Color,
fn bg<C>(&self) -> BgColorDisplay<'_, C, Self>where
C: Color,
§fn on_yellow<'a>(&'a self) -> BgColorDisplay<'a, Yellow, Self>
fn on_yellow<'a>(&'a self) -> BgColorDisplay<'a, Yellow, Self>
§fn magenta<'a>(&'a self) -> FgColorDisplay<'a, Magenta, Self>
fn magenta<'a>(&'a self) -> FgColorDisplay<'a, Magenta, Self>
§fn on_magenta<'a>(&'a self) -> BgColorDisplay<'a, Magenta, Self>
fn on_magenta<'a>(&'a self) -> BgColorDisplay<'a, Magenta, Self>
§fn on_purple<'a>(&'a self) -> BgColorDisplay<'a, Magenta, Self>
fn on_purple<'a>(&'a self) -> BgColorDisplay<'a, Magenta, Self>
§fn default_color<'a>(&'a self) -> FgColorDisplay<'a, Default, Self>
fn default_color<'a>(&'a self) -> FgColorDisplay<'a, Default, Self>
§fn on_default_color<'a>(&'a self) -> BgColorDisplay<'a, Default, Self>
fn on_default_color<'a>(&'a self) -> BgColorDisplay<'a, Default, Self>
§fn bright_black<'a>(&'a self) -> FgColorDisplay<'a, BrightBlack, Self>
fn bright_black<'a>(&'a self) -> FgColorDisplay<'a, BrightBlack, Self>
§fn on_bright_black<'a>(&'a self) -> BgColorDisplay<'a, BrightBlack, Self>
fn on_bright_black<'a>(&'a self) -> BgColorDisplay<'a, BrightBlack, Self>
§fn bright_red<'a>(&'a self) -> FgColorDisplay<'a, BrightRed, Self>
fn bright_red<'a>(&'a self) -> FgColorDisplay<'a, BrightRed, Self>
§fn on_bright_red<'a>(&'a self) -> BgColorDisplay<'a, BrightRed, Self>
fn on_bright_red<'a>(&'a self) -> BgColorDisplay<'a, BrightRed, Self>
§fn bright_green<'a>(&'a self) -> FgColorDisplay<'a, BrightGreen, Self>
fn bright_green<'a>(&'a self) -> FgColorDisplay<'a, BrightGreen, Self>
§fn on_bright_green<'a>(&'a self) -> BgColorDisplay<'a, BrightGreen, Self>
fn on_bright_green<'a>(&'a self) -> BgColorDisplay<'a, BrightGreen, Self>
§fn bright_yellow<'a>(&'a self) -> FgColorDisplay<'a, BrightYellow, Self>
fn bright_yellow<'a>(&'a self) -> FgColorDisplay<'a, BrightYellow, Self>
§fn on_bright_yellow<'a>(&'a self) -> BgColorDisplay<'a, BrightYellow, Self>
fn on_bright_yellow<'a>(&'a self) -> BgColorDisplay<'a, BrightYellow, Self>
§fn bright_blue<'a>(&'a self) -> FgColorDisplay<'a, BrightBlue, Self>
fn bright_blue<'a>(&'a self) -> FgColorDisplay<'a, BrightBlue, Self>
§fn on_bright_blue<'a>(&'a self) -> BgColorDisplay<'a, BrightBlue, Self>
fn on_bright_blue<'a>(&'a self) -> BgColorDisplay<'a, BrightBlue, Self>
§fn bright_magenta<'a>(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
fn bright_magenta<'a>(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
§fn on_bright_magenta<'a>(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
fn on_bright_magenta<'a>(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
§fn bright_purple<'a>(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
fn bright_purple<'a>(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
§fn on_bright_purple<'a>(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
fn on_bright_purple<'a>(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
§fn bright_cyan<'a>(&'a self) -> FgColorDisplay<'a, BrightCyan, Self>
fn bright_cyan<'a>(&'a self) -> FgColorDisplay<'a, BrightCyan, Self>
§fn on_bright_cyan<'a>(&'a self) -> BgColorDisplay<'a, BrightCyan, Self>
fn on_bright_cyan<'a>(&'a self) -> BgColorDisplay<'a, BrightCyan, Self>
§fn bright_white<'a>(&'a self) -> FgColorDisplay<'a, BrightWhite, Self>
fn bright_white<'a>(&'a self) -> FgColorDisplay<'a, BrightWhite, Self>
§fn on_bright_white<'a>(&'a self) -> BgColorDisplay<'a, BrightWhite, Self>
fn on_bright_white<'a>(&'a self) -> BgColorDisplay<'a, BrightWhite, Self>
§fn blink_fast<'a>(&'a self) -> BlinkFastDisplay<'a, Self>
fn blink_fast<'a>(&'a self) -> BlinkFastDisplay<'a, Self>
§fn strikethrough<'a>(&'a self) -> StrikeThroughDisplay<'a, Self>
fn strikethrough<'a>(&'a self) -> StrikeThroughDisplay<'a, Self>
§fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self>where
Color: DynColor,
fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self>where
Color: DynColor,
OwoColorize::fg
or
a color-specific method, such as OwoColorize::green
, Read more§fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self>where
Color: DynColor,
fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self>where
Color: DynColor,
OwoColorize::bg
or
a color-specific method, such as OwoColorize::on_yellow
, Read more