Rules, Emacs comparisons, limits and open points

Rules a plugin author must know

The design states six rules; the rest are the idioms that follow from them.

1. Your plugin.ss runs top to bottom when your plugin turns on. Everything it sets up through the core (entries made through verbs, hook entries, option layers, timers, jobs, ties, on-end actions) is yours and is undone, newest first, when it turns off or reloads.
2. Your ordinary variables start fresh each run. Your own working state belongs in them. What must outlive a reload (a reader, a drawing worker) is started again from the top level of your file, from saved data.
3. You change another plugin’s state only by calling its contract. You cannot write its data; the build refuses set! on another plugin’s saved data.
4. What the user cares about is saved data; settings are options; what you add to another plugin’s things goes through its contract’s verbs. Keep in saved data only data whose shape your plugin (or a contract you implement) defines, as plain data, a persistent map when keyed, a define-plain-record for a fixed shape. Never change saved lists in place.
5. Hold other plugins’ things by id. Ids come from new-id and are never reused; check live? (or the provider’s equivalent) before use.
6. An exported variable is a constant.
7. Your plugin reruns by itself when something it used while starting changes (a provider reloaded, swapped or turned off). You write nothing for it.
8. Heavy work goes to a worker: define-worker at the top level, start-job to run it. A worker sees only its input, standard Scheme, a listed set of Chez procedures, the plain-data library, post, next-input and sleep. Code it shares with your plugin goes in a file both include.
9. Start a job for each change, for: what it is about, and you never see a stale result. Work not restarted on every change checks in on-result that what it was for is still current.
10. A worker that waits on input needs its own way out (closing what it reads), because a worker blocked in a system call cannot be stopped.
11. A worker that keeps results across iterations keeps them in a few large flat objects (vectors, strings), not many small lists; this keeps garbage collection short.
12. A start does no blocking work and cannot wait; it starts a worker instead. An end cannot wait either.
13. A command paused inside a plugin that changes is quit, as by C-g. After any pause, get values from other plugins again: they may have reloaded with a new shape.
14. A procedure of yours that makes something for its caller says whose it is: the user’s (it stays) or the caller’s (tie it with on-caller-end, and forget-caller-end when it goes by other means). A verb of yours makes its entries with as-caller, so they are the caller’s. The caller is the code that contains the call.
15. What you want drawn goes through the display’s verbs, because a frame is due only when core state changes.
16. Use a contract you can do without under (provided? 'c).
17. A process the user starts is processes:start!; one your plugin needs for itself is processes:start-own.
18. A contract meant to be implemented by others has a contract.ss, and declares its saved data there, whole.
19. A macro use must not expand to definitions followed by an expression (it is refused with its line). Macros and record types change only by reloading.
20. Do not use eval (reported: it reaches around imports) or fork-thread (refused: use a worker).
21. Public procedures check their arguments at entry (assert, assertion-violation) and name themselves in the error; code inside trusts its arguments.
22. Names: a procedure called for its effect on something that exists ends in !; one that makes something new does not; nor does syntax. A contract’s procedures take optional positional arguments or property lists, not keywords: keywords are the core’s.

Rules a user must know

1. init.ss runs once, top to bottom. (use-plugin p key: value …) picks a plugin and its options; (use-plugin a b c) picks several. A plugin starts at its line, or earlier when something needs it. A plugin not listed never starts.
2. A change belongs to where you wrote it: a plugin, an init.ss line, or your session (M-:). Removing the line removes the change; ending the session removes the session’s changes.
3. reload-config applies only what changed. If a changed line fails, what was running stays.
4. C-M-x on a definition takes effect at once and lasts until that plugin is reloaded from its file.
5. Your data is saved after every command, when a storage plugin is on. After a crash you lose at most what an unfinished command did.
6. Turning a plugin off leaves Tuna as if it had never been on, except your data.
7. Your shells keep running when the terminal goes and when you quit; killing a shell’s buffer ends it; list-processes shows them all.

Emacs comparisons that matter

Known limits

None blocked approval. Each is a thing the design cannot do, or does only by a rule an author must follow.

• Code blocked in a system call cannot be stopped from inside Tuna, whether in a worker or in a plugin’s start. A cancelled worker is reported after 3 s; a start blocked this way ignores its time limit. Racket can interrupt more of these cases; Chez cannot.
• Old data after a pause. A command that got data from another plugin, paused at a prompt, and resumed after that plugin reloaded with a new shape, calls new code with old data. Quitting more commands would break other cases, so it is a rule: get values again after a pause.
• Lists are always mutable in Chez, so a plugin could change a saved list in place and the core would not see it.
• A hand-written check must follow the data’s shape. If a plugin changes the shape of its saved data but not its check, old data is accepted in the wrong shape. Data declared with define-plain-record gets its check from its fields, so this applies only to hand-written checks.
• Only persistent maps are undone key by key after a failed start. A whole value written by two starts, one of which fails, keeps the failing start’s write, and this is reported.
• The worker’s list of Chez procedures is kept by hand. A missing one is refused with a clear message; one wrongly present could let a worker reach shared state. The owner reviews the list once before it is fixed.
• Nested calls charge the plugin whose code made the call. If plugin B makes a view for its caller A through plugin C’s procedure, the view is B’s, not A’s.
• Saved data about another plugin’s things can go stale while that plugin is off: a buffer killed while modes is off leaves an entry in modes’ data. Plugins clean such entries when they start, as the process service does.
• While the process service is off, killing a shell’s buffer ends the shell only when the service is on again.
• Without a storage plugin, nothing is saved. That is by design (storage is a policy), but removing journal-store from init.ss silently stops saving.
• Measured only with small worker results: whether a worker posting large lists slows garbage collection in the editor is not verified; vectors and strings are the cheap form.
• The cost of reading an option with scopes is to be measured when it is built; the design reads the scope procedures at each read.

Open and proposed

For the owner to decide:

• proposed defaults.ss: Tuna ships one file of the default use-plugin lines, which init.ss includes in one line. See the entry.
• proposed Reusing the existing build and the branch names. The branch core already has a build (it refuses any Chez but threaded 10.4.1; a compile warning fails it), a Makefile, a small test library and the single-executable packaging, made before the design and independent of it. The proposal: rename the old core and stage-2 branches old-core and old-stage-2 (kept until you delete them), start a new core from that build’s last commit, trim three file-header comments that break the comment rule, and use it as the branch each stage merges into.

Decided by the primary agent (tell him if you disagree):

• Saved data is written by a storage plugin, journal-store, filling the (storage) contract, not by the core. The core keeps saved data and decides when changed entries must be written; where and how they reach disk is a policy.
• Ties are plain data, (on-caller-end (buffers:kill! id)) recorded as the call’s name and arguments, so they are saved with the session and never run an old provider’s code after a swap.
• Input from the browser reaches the editor through the core’s input hand-over, which takes plain data from any thread.
• The author’s API of this guide: verbs and as-caller, hooks, text procedures on the current buffer, define-saved, on-end, dynamic values, plain records and checks, scoped layers and hook entries, and the renames.

Not yet named or fixed (small; settled while building): the names of the commands for turning off, reloading, swapping and ending the session; where init.ss and your own plugins live on disk; the grace period before a forced quit; the start time limit (5 s in the prototype); the persistent map library’s name.

The prototype and this guide

The design was proven with a prototype that used older names. This guide follows the approved API; where the prototype differs, the guide is right.