Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 14:48:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

documentation updates

Browse source
This commit is contained in:
Vern Paxson 2023-06-16 16:54:46 -07:00 • committed by Arne Welzel
parent bd30baf42f
commit ed828ec92b
1 changed files with 9 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

43
src/script_opt/ZAM/README.md
View file

@ -41,35 +41,29 @@ the _Logging Framework_, for example, and thus you won't see much improvement.
* Those two factors add up to gains very often on the order of only 10-15%,
rather than something a lot more dramatic.
* In addition, there are some
[types of scripts that currently can't be compiled](#Scripts-that-cannot-be-compiled),
and thus will remain interpreted. If your processing bottlenecks in such
scripts, you won't see much in the way of gains.
<br>
## Known Issues
Here we list various issues with using script optimization, including both
deficiencies (problems to eventually fix) and incompatibilities (differences
in behavior from the default of script interpretation, not necessarily
fixable). For each, the corresponding list is roughly ordered from
you're-most-likely-to-care-about-it to you're-less-likely-to-care, though
of course this varies for different users.
deficiencies (things that don't work as well as you might like)
and incompatibilities (differences in behavior from the default
of script interpretation).
<br>
### Deficiencies to eventually fix:
### Deficiencies:
* Error messages in compiled scripts have diminished identifying
* Run-time error messages in compiled scripts have diminished identifying
information.
* The optimizer assumes you have ensured initialization of your variables.
If your script uses a variable that hasn't been set, the compiled code may
crash or behave aberrantly. You can use the `-u` command-line flag to find such potential usage issues.
* Certain complex "when" expressions may fail to reevaluate when elements
of the expression are modified by compiled scripts.
* When printing scripts (such as in some error messages), the names of
variables often reflect internal temporaries rather than the original
variables.
<br>
@ -77,30 +71,11 @@ of the expression are modified by compiled scripts.
* ZAM ignores `assert` statements.
* When printing scripts (such as in some error messages), the names of
variables often reflect internal temporaries rather than the original
variables.
* The `same_object()` BiF will always deem two non-container values as
different.
<br>
### Scripts that cannot be compiled:
The ZAM optimizer does not compile scripts that include "when" statements or
lambda expressions. These will take substantial work to support. It also
will not inline such scripts, nor will it inline scripts that are either
directly or indirectly recursive.
You can get a list of non-compilable scripts using
`-O ZAM -O report-uncompilable`. For recursive scripts, use
`-O report-recursive` (no `-O ZAM` required, since it doesn't apply to the
alternative optimization, `-O gen-C++`).
<br>
## Script Optimization Options
Users will generally simply use `-O ZAM` to invoke the script optimizer.
@ -120,7 +95,7 @@ issues:
|`optimize-AST` | Optimize the (transform) AST; implies `xform`.|
|`profile-ZAM` | Generate to _stdout_ a ZAM execution profile. (Requires configuring with `--enable-debug`.)|
|`report-recursive` | Report on recursive functions and exit.|
|`report-uncompilable` | Report on uncompilable functions and exit.|
|`report-uncompilable` | Report on uncompilable functions and exit. For ZAM, all functions should be compilable.|
|`xform` | Transform scripts to "reduced" form.|
<br>