changeset 32429:ffc410f26506

doc: Rename virtual machine / VM as bytecode interpreter Following the discussion at https://octave.discourse.group/t/place-all-vm-functions-under-vm-prefix/4873/18 this changeset makes the following nomenclature change in documentation: * virtual machine / VM / VM evaluator --> bytecode interpreter * VM code / related phrases --> bytecode Files changed: * Rename vm.m as bytecode.m. * scripts/help/module.mk: make the above change. * bytecode.m: update with new terms. * vectorize.txi: edit to match. * NEWS.9.md: edit to match.
author Arun Giridhar <arungiridhar@gmail.com>
date Tue, 24 Oct 2023 16:12:44 -0400
parents e1a85e723056
children 868172fa8849
files doc/interpreter/vectorize.txi etc/NEWS.9.md scripts/help/bytecode.m scripts/help/module.mk scripts/help/vm.m
diffstat 5 files changed, 81 insertions(+), 83 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/vectorize.txi	Tue Oct 24 01:35:52 2023 -0400
+++ b/doc/interpreter/vectorize.txi	Tue Oct 24 16:12:44 2023 -0400
@@ -43,7 +43,7 @@
 * Function Application::       Applying functions to arrays, cells, and structs
 * Accumulation::               Accumulation functions
 * Memoization::                Memoization techniques
-* VM evaluator::               VM evaluator
+* Bytecode interpreter::       Bytecode interpreter
 * Miscellaneous Techniques::   Other techniques for speeding up code
 * Examples::
 @end menu
@@ -629,14 +629,14 @@
 
 @DOCSTRING(clearAllMemoizedCaches)
 
-@node VM evaluator
-@section VM evaluator
+@node Bytecode interpreter
+@section Bytecode interpreter
 
-Octave's virtual machine (VM) evaluator allows faster execution of existing
-code.  Octave versions 9 onwards have the VM built-in by default.  The VM is
-still considered experimental, therefore the VM functions are not explicitly
-documented in this manual.  Instead, the command @code{vm} will list several
-VM-related functions, including how to enable it.
+Octave's bytecode interpreter allows faster execution of existing
+code.  Octave versions 9 onwards have the bytecode interpreter built-in
+by default.  It is still considered experimental, therefore the related
+functions are not explicitly documented in this manual.  Instead, the command
+@code{bytecode} describes how to invoke it.
 
 @node Miscellaneous Techniques
 @section Miscellaneous Techniques
--- a/etc/NEWS.9.md	Tue Oct 24 01:35:52 2023 -0400
+++ b/etc/NEWS.9.md	Tue Oct 24 16:12:44 2023 -0400
@@ -3,13 +3,12 @@
 
 ### General improvements
 
-- Octave now has an experimental virtual machine (VM) for just-in-time (JIT)
-evaluation of m-code.  Speedups from 2X to 40X have been observed for different
-kinds of m-code.  This feature is considered experimental for now.  M-code
-that cannot be handled by the VM yet falls back automatically to the existing
-interpreter.  User tests of the VM evaluator are encouraged.  To learn more
-about VM commands, type `vm` or `help vm` at the Octave prompt, or refer the
-Octave manual section 19.6 on the VM.
+- Octave now has an experimental bytecode interpreter for m-code.  Speedups
+from 2X to 40X have been observed for different kinds of m-code.  This feature
+is considered experimental for now.  M-code that cannot yet be handled by the
+bytecode interpreter falls back automatically to the existing tree-walker
+interpreter.  User tests of the bytecode interpreter are encouraged.  To learn
+more, type `bytecode` or `help bytecode` at the Octave prompt.
 
 - `oruntests`: The current directory now changes to the directory
 containing the files with the tests for the duration of the test.  This
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/help/bytecode.m	Tue Oct 24 16:12:44 2023 -0400
@@ -0,0 +1,66 @@
+########################################################################
+##
+## Copyright (C) 2023 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## This file is part of Octave.
+##
+## Octave is free software: you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn {} {} bytecode ()
+## Summary of commands related to Octave's bytecode interpreter.
+##
+## As of Octave 9, the bytecode interpreter is considered @emph{experimental}.
+## The user is encouraged to test it with that in mind. All bytecode functions,
+## being experimental, may be renamed in future.
+##
+## To switch on the bytecode interpreter, type: @code{__vm_enable__ (1)}
+##
+## To switch it off, type: @code{__vm_enable__ (0)}
+##
+## To always use it, add @code{__vm_enable__ (1)}
+## to your Octave startup file (.octaverc or similar).
+##
+## For more information on each command and available options use
+## @code{help CMD}.
+##
+## The other bytecode commands available in Octave are:
+##
+## @table @code
+## @item __vm_compile__
+## Compile a specified function to bytecode.
+##
+## @item __vm_profile__
+## Profile the code running in the bytecode interpreter.
+##
+## @end table
+##
+## There are also several private functions whose names also begin with
+## @code{__vm_}.  These are meant for developer use.
+##
+## @noindent
+## @end deftypefn
+
+function bytecode ()
+  help ("bytecode");
+endfunction
+
+## Mark file as being tested.  No real test needed for a documentation .m file
+%!assert (1)
--- a/scripts/help/module.mk	Tue Oct 24 01:35:52 2023 -0400
+++ b/scripts/help/module.mk	Tue Oct 24 16:12:44 2023 -0400
@@ -13,6 +13,7 @@
   %reldir%/__unimplemented__.m \
   %reldir%/ans.m \
   %reldir%/bessel.m \
+  %reldir%/bytecode.m \
   %reldir%/debug.m \
   %reldir%/doc.m \
   %reldir%/doc_cache_create.m \
@@ -23,7 +24,6 @@
   %reldir%/print_usage.m \
   %reldir%/slash.m \
   %reldir%/type.m \
-  %reldir%/vm.m \
   %reldir%/warning_ids.m \
   %reldir%/which.m
 
--- a/scripts/help/vm.m	Tue Oct 24 01:35:52 2023 -0400
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,67 +0,0 @@
-########################################################################
-##
-## Copyright (C) 2023 The Octave Project Developers
-##
-## See the file COPYRIGHT.md in the top-level directory of this
-## distribution or <https://octave.org/copyright/>.
-##
-## This file is part of Octave.
-##
-## Octave is free software: you can redistribute it and/or modify it
-## under the terms of the GNU General Public License as published by
-## the Free Software Foundation, either version 3 of the License, or
-## (at your option) any later version.
-##
-## Octave is distributed in the hope that it will be useful, but
-## WITHOUT ANY WARRANTY; without even the implied warranty of
-## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-## GNU General Public License for more details.
-##
-## You should have received a copy of the GNU General Public License
-## along with Octave; see the file COPYING.  If not, see
-## <https://www.gnu.org/licenses/>.
-##
-########################################################################
-
-## -*- texinfo -*-
-## @deftypefn {} {} vm ()
-## Summary of commands related to Octave's virtual machine (VM) evaluator.
-##
-## As of Octave 9, the VM evaluator is considered @emph{experimental}.
-## The user is encouraged to test the VM with that in mind. All VM functions,
-## being experimental, may be renamed in future. Currently they are
-## all named @code{__vm_X__}.
-##
-## To switch on the VM, type: @code{__vm_enable__ (1)}
-##
-## To switch off the VM, type: @code{__vm_enable__ (0)}
-##
-## To always use the VM, add @code{__vm_enable__ (1)}
-## to your Octave startup file (.octaverc or similar).
-##
-## For more information on each command and available options use
-## @code{help CMD}.
-##
-## The other VM commands available in Octave are:
-##
-## @table @code
-## @item __vm_compile__
-## Compile a specified function to bytecode.
-##
-## @item __vm_profile__
-## Profile the code running in the VM.
-##
-## @end table
-##
-## There are also several private VM functions whose names also begin with
-## @code{__vm_}.  These are meant for developer use.
-##
-## @noindent
-## @end deftypefn
-
-function vm ()
-  help ("vm");
-endfunction
-
-## Mark file as being tested.  No real test needed for a documentation .m file
-%!assert (1)