Mercurial > octave
changeset 32969:a3b312564056 bytecode-interpreter
doc: Update documentation for VM functions.
* compile.cc (__vm_clear_cache__): Add 1-line summary of function and see also note.
* compile.cc (__vm_print_trace__): Delete extra parenthesis in function prototype.
Improve wording for documentation.
* compile.cc (__ref_count__): Delete extra parenthesis in function prototype.
* compile.cc (__vm_is_executing__): Use standard output name of "tf" for
true/false value. Add see also note.
* compile.cc (__vm_profile__): Place Programming Note outside of table of options.
* compile.cc (__vm_print_bytecode__): Rename output variable to "code", not "success".
Use standard abbreviation "fcn" for function. Add see also note.
* compile.cc (__vm_is_compiled__): Use standard output name of "tf" for
true/false value. Improve wording for documentation. Add see also note.
* compile.cc (__vm_compile__): Use standard output name of "status" for
result of operation. Use standard abbreviation "fcn" for function. Improve
wording for documentation. Add see also note.
* compile.cc (__vm_enable__): Delete use of @seealso macro and replace with see
also note.
* bytecode.m: Use @file macro around filenames. Improve wording of
documentation. Add see also note.
| author | Rik <rik@octave.org> |
|---|---|
| date | Wed, 07 Feb 2024 18:18:01 -0800 |
| parents | 338860f6d680 |
| children | 7f983dc61c09 |
| files | libinterp/corefcn/compile.cc scripts/help/bytecode.m |
| diffstat | 2 files changed, 47 insertions(+), 42 deletions(-) [+] |
line wrap: on
line diff
--- a/libinterp/corefcn/compile.cc Sat Feb 03 09:18:30 2024 +0800 +++ b/libinterp/corefcn/compile.cc Wed Feb 07 18:18:01 2024 -0800 @@ -104,9 +104,12 @@ DEFUN (__vm_clear_cache__, , , doc: /* -*- texinfo -*- @deftypefn {} {@var{val} =} __vm_clear_cache__ () - Internal function. +Clear cache of bytecode-compiled functions. + +@c FIXME: Use seealso macro when functions are no longer experimental. +See also: __vm_compile__. @end deftypefn */) { #if defined (OCTAVE_ENABLE_BYTECODE_EVALUATOR) @@ -124,15 +127,14 @@ DEFUN (__vm_print_trace__, , , doc: /* -*- texinfo -*- -@deftypefn {} {@var{print_trace} =} __vm_print_trace__ ()) - +@deftypefn {} {@var{print_trace} =} __vm_print_trace__ () Internal function. Print a debug trace from the VM@. -Toggles on or off each call. +The print state toggles on or off with each call to the function. -There has to be a breakpoint set in some file for the trace to actually print +There must be a breakpoint set in an m-file for the trace to actually print anything. The return value is true if a trace will be printed and false otherwise. @@ -154,12 +156,10 @@ DEFUN (__ref_count__, args, , doc: /* -*- texinfo -*- -@deftypefn {} {@var{count} =} __ref_count__ (@var{obj})) - +@deftypefn {} {@var{count} =} __ref_count__ (@var{obj}) Internal function. Return the reference count for an object. - @end deftypefn */) { int nargin = args.length (); @@ -174,13 +174,14 @@ DEFMETHOD (__vm_is_executing__, interp, , , doc: /* -*- texinfo -*- -@deftypefn {} {@var{is_executing} =} __vm_is_executing__ ()) - +@deftypefn {} {@var{tf} =} __vm_is_executing__ () Internal function. Return true if the VM is executing the function calling @code{__vm_is_executing__ ()}, and false otherwise. +@c FIXME: Use seealso macro when functions are no longer experimental. +See also: __vm_enable__. @end deftypefn */) { #if defined (OCTAVE_ENABLE_BYTECODE_EVALUATOR) @@ -214,7 +215,6 @@ @deftypefnx {} {} __vm_profile__ clear @deftypefnx {} {@var{T} =} __vm_profile__ ("info") @deftypefnx {} {} __vm_profile__ - Internal function. Profile code running in the VM. @@ -241,11 +241,11 @@ @item __vm_profile__ info Print the profiler data. +@end table + Programming Note: The calling form that returns profiler data in a variable is not implemented yet. -@end table - @end deftypefn */) { #if defined (OCTAVE_ENABLE_BYTECODE_EVALUATOR) @@ -333,13 +333,14 @@ DEFMETHOD (__vm_print_bytecode__, interp, args, , doc: /* -*- texinfo -*- -@deftypefn {} {@var{success} =} __vm_print_bytecode__ (@var{fn_name})) -@deftypefnx {} {@var{success} =} __vm_print_bytecode__ (@var{fn_handle})) - +@deftypefn {} {@var{code} =} __vm_print_bytecode__ (@var{fcn_name}) +@deftypefnx {} {@var{code} =} __vm_print_bytecode__ (@var{fcn_handle}) Internal function. -Prints the bytecode of a function name or function handle, if any. +Print the bytecode of a function name or function handle. +@c FIXME: Use seealso macro when functions are no longer experimental. +See also: __vm_compile__. @end deftypefn */) { #if defined (OCTAVE_ENABLE_BYTECODE_EVALUATOR) @@ -419,15 +420,15 @@ DEFMETHOD (__vm_is_compiled__, interp, args, , doc: /* -*- texinfo -*- -@deftypefn {} {@var{is_compiled} =} __vm_is_compiled__ (@var{fn_name}) -@deftypefnx {} {@var{is_compiled} =} __vm_is_compiled__ (@var{fn_handle}) - +@deftypefn {} {@var{tf} =} __vm_is_compiled__ (@var{fcn_name}) +@deftypefnx {} {@var{tf} =} __vm_is_compiled__ (@var{fcn_handle}) Internal function. -Returns true if the specified function name or function handle is compiled. +Return true if the specified function name or function handle has been +compiled to bytecode, and false otherwise. -False otherwise. - +@c FIXME: Use seealso macro when functions are no longer experimental. +See also: __vm_compile__. @end deftypefn */) { #if defined (OCTAVE_ENABLE_BYTECODE_EVALUATOR) @@ -494,25 +495,27 @@ DEFMETHOD (__vm_compile__, interp, args, , doc: /* -*- texinfo -*- -@deftypefn {} {@var{success} =} __vm_compile__ (@var{fn_name}) -@deftypefnx {} {@var{success} =} __vm_compile__ (@var{fn_name}, "clear") -@deftypefnx {} {@var{success} =} __vm_compile__ (@var{fn_name}, "print") - +@deftypefn {} {@var{status} =} __vm_compile__ (@var{fcn_name}) +@deftypefnx {} {@var{status} =} __vm_compile__ (@var{fcn_name}, "print") +@deftypefnx {} {@var{status} =} __vm_compile__ (@var{fcn_name}, "clear") Internal function. Compile the specified function to bytecode. -The compiled function and its subfunctions will be executed -by the VM when called. - -Returns true on success, otherwise false. - -Don't recompile or clear the bytecode of a running function with __vm_compile__. +The compiled function and its subfunctions will be executed by the VM when +called. The @qcode{"print"} option prints the bytecode after compilation. -The @qcode{"clear"} option removes the bytecode from the function instead. +The @qcode{"clear"} option removes the bytecode from the VM instead. + +Return true on success, and false otherwise. +@strong{Note:}: Do not recompile or clear the bytecode of a running function +with @code{__vm_compile__}. + +@c FIXME: Use seealso macro when functions are no longer experimental. +See also: __vm_print_bytecode__, __vm_clear_cache__. @end deftypefn */) { #if defined (OCTAVE_ENABLE_BYTECODE_EVALUATOR) @@ -666,8 +669,8 @@ @strong{Warning:} The virtual machine feature is experimental. -The default value is false while the VM is still experimental. -Users must explicitly call @code{__vm_enable__ (1)} to use it. +The default value is false while the VM is still experimental. Users must +explicitly call @code{__vm_enable__ (1)} to use it. When false, Octave uses a traditional tree walker to evaluate statements parsed from m-code. When true, Octave translates parsed statements to an intermediate @@ -681,8 +684,8 @@ regardless of the state of @code{__vm_enable__}, until the bytecode is cleared by, e.g., @qcode{"clear all"}, or a modification to the function's m-file. -@seealso{__vm_compile__} - +@c FIXME: Use seealso macro when functions are no longer experimental. +See also: __vm_compile__. @end deftypefn */) { #if defined (OCTAVE_ENABLE_BYTECODE_EVALUATOR)
--- a/scripts/help/bytecode.m Sat Feb 03 09:18:30 2024 +0800 +++ b/scripts/help/bytecode.m Wed Feb 07 18:18:01 2024 -0800 @@ -36,12 +36,12 @@ ## 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). +## to your Octave startup file (@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: +## Other useful bytecode commands available in Octave are: ## ## @table @code ## @item __vm_compile__ @@ -53,14 +53,16 @@ ## @end table ## ## There are also several private functions whose names also begin with -## @code{__vm_}. These are meant for developer use. +## @code{__vm_}. These are intended for developer use. ## -## @noindent +## @c FIXME: Use seealso macro when functions are no longer experimental. +## See also: __vm_enable__, __vm_compile__, __vm_profile__. ## @end deftypefn function bytecode () help ("bytecode"); endfunction + ## Mark file as being tested. No real test needed for a documentation .m file %!assert (1)