diff --git a/mathstream/README.md b/mathstream/README.md index 864044c..1e97d04 100644 --- a/mathstream/README.md +++ b/mathstream/README.md @@ -62,6 +62,11 @@ Each arithmetic call writes its result back into `instance/log` (configurable vi Divide-by-zero scenarios raise the custom `DivideByZeroError` so callers can distinguish mathstream issues from Python’s native exceptions. +## Performance Tips + +- **Reuse literal streams** – `StreamNumber(literal=...)` persists a hashed copy under `LOG_DIR`. Reuse those objects (or their filenames) across operations instead of recreating them every call. Repeated literal construction churns the filesystem: you pay the cost to rewrite identical data, poll the logger database, and spike disk I/O. Hang on to the staged literal or memoize it so it can be streamed repeatedly without rewriting. +- **Free aggressively** – When a staged result or literal copy is no longer needed, call `free_stream()` (or use `with StreamNumber(...) as n:`) so the reference count drops immediately. This keeps the cache tidy and reduces the chance that stale literal files pile up between runs. + ## Example Script `test.py` in the repository root demonstrates a minimal workflow: