Mercurial > octave
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)