mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-19 08:39:02 +03:00
docs(cli-rs): remove obsolete design-section citations
Keep the dispatch, loading and resource-limit rules in terms of what the host does. Remove section numbers that no longer resolve to maintained documentation. The native rollback test and scoped clippy for both plugin crates passed.
This commit is contained in:
@@ -13,7 +13,7 @@ use std::sync::{Arc, PoisonError, RwLock};
|
||||
use serde::Serialize;
|
||||
use serde::de::DeserializeOwned;
|
||||
|
||||
/// The entries of one plugin's mailbox. 256 is the pipe's number of pending ordered events (4.3), a starting value.
|
||||
/// Maximum pending messages per plugin.
|
||||
pub const BOUND: usize = 256;
|
||||
|
||||
/// Why a send was refused; the message comes back.
|
||||
|
||||
@@ -625,7 +625,6 @@ impl Core {
|
||||
};
|
||||
let plugin = &self.claim.plugin;
|
||||
let mut state = self.state.borrow_mut();
|
||||
// Content past what the plugin may hold is not kept: a node that shows it is a placeholder (4.2).
|
||||
let (admitted, over) = surface::admit_content(plugin, given);
|
||||
let Held { tree, content, last, measures, dropped, .. } = &mut *state;
|
||||
let unheld: HashSet<ContentRef> = dropped.union(&over).copied().collect();
|
||||
@@ -722,9 +721,7 @@ impl Core {
|
||||
self.state.borrow().tree.holds_fence()
|
||||
}
|
||||
|
||||
/// Drops the tree, so a later view builds whole, and the pictures of inline images, which only the tree named.
|
||||
/// The content handles and memo values its views gave stay with the mount until it ends or the plugin releases
|
||||
/// them (4.2), as a library keeps its table: a later view may name them again.
|
||||
/// Keep the mount’s content and memo handles: a later view can reuse them.
|
||||
fn wipe(&self) {
|
||||
let mut state = self.state.borrow_mut();
|
||||
state.tree.clear(&self.root);
|
||||
|
||||
@@ -741,7 +741,6 @@ impl Monitor {
|
||||
return backlog;
|
||||
}
|
||||
stats.slow.then(|| {
|
||||
// The host's time for its nodes goes beside its own calls (4.4).
|
||||
let kinds: Vec<String> = stats
|
||||
.kinds
|
||||
.iter()
|
||||
@@ -755,7 +754,6 @@ impl Monitor {
|
||||
format!("{kind} {:.1}/{:.1}/{:.1} ms", ms(at(0.5)), ms(at(0.99)), ms(samples.worst))
|
||||
})
|
||||
.collect();
|
||||
// How long it took to start, as the manager's details say it (4.4); a healthy row says nothing.
|
||||
let start: Vec<String> = [("load", stats.load), ("setup", stats.setup)]
|
||||
.into_iter()
|
||||
.filter_map(|(name, took)| Some(format!("{name} {:.1} ms", ms(took?))))
|
||||
|
||||
@@ -123,7 +123,7 @@ pub trait Host: 'static {
|
||||
fn slow_changed(&self) {}
|
||||
/// Ends what the host shows for an activation of plugin `id` that ended (it was disabled, replaced, unloaded, or
|
||||
/// failed): the dialog it opened, if that activation is no longer [`Registry::live`], so nothing of an old build can
|
||||
/// run (4.14). Called outside every plugin callback.
|
||||
/// run. Called outside every plugin callback.
|
||||
fn revoked(&self, _id: &str) {}
|
||||
/// Notifies the user once per project build that needs approval, outside plugin callbacks.
|
||||
fn pending(&self, target: &str) {
|
||||
@@ -1301,7 +1301,7 @@ impl Scope {
|
||||
|
||||
/// Ends the activation, so no call, reply or wake reaches the plugin after, then disposes its registrations `api`
|
||||
/// with the host, or without it once it is gone. A plugin that failed is called no more, so its dispose callbacks
|
||||
/// do not run (4.14; TS runs no plugin code after a failed setup either).
|
||||
/// do not run.
|
||||
fn dispose(self: &Rc<Self>, api: &mut abi::Registered) {
|
||||
self.revoked.take().into_iter().for_each(Disposer::dispose);
|
||||
// First, so nothing the dispose callbacks set off calls the plugin back.
|
||||
@@ -1835,7 +1835,7 @@ pub(crate) fn fail(
|
||||
activation: &Rc<Activation>,
|
||||
error: String,
|
||||
) {
|
||||
// A failure is final, and the first cause is the one reported (4.14): a plugin that failed cannot fail again.
|
||||
// The first failure is the one shown to the user.
|
||||
if failure.borrow().is_some() {
|
||||
return;
|
||||
}
|
||||
@@ -1849,8 +1849,7 @@ pub(crate) fn fail(
|
||||
// The fences it drew fall back to the code view, as the ones it draws from now on do.
|
||||
behave::remount(host);
|
||||
});
|
||||
// The queued redraw still runs on a disposed activation, so the claims draw empty once. Disposing tells its threads
|
||||
// to end and drops what they sent (4.14: a wake for a plugin that is not active).
|
||||
// Invalidate before disposal so mounted claims clear their last render.
|
||||
activation.invalidate();
|
||||
activation.dispose();
|
||||
}
|
||||
@@ -2205,7 +2204,6 @@ impl Setup<'_> {
|
||||
) {
|
||||
let (owner, activation) = (Rc::downgrade(self.host), owners.activation.clone());
|
||||
let plugin: Rc<str> = Rc::from(self.id);
|
||||
// The host's work for the plugin's nodes is timed apart from its calls, as its host time (4.4).
|
||||
let (monitor, slot) = (self.monitor.clone(), self.monitor.slot(&self.artifact()));
|
||||
let host_time: surface::HostTime = Rc::new(move |work| monitor.host(slot, work));
|
||||
match surface.at.clone() {
|
||||
@@ -2430,7 +2428,7 @@ struct Registration {
|
||||
}
|
||||
|
||||
impl Registration {
|
||||
/// Whether a call of this activation panicked: it contributes nothing, and is called no more (4.14).
|
||||
/// Whether a call of this activation panicked: it contributes nothing, and is called no more.
|
||||
fn panicked(&self) -> bool {
|
||||
self.failure.as_ref().is_some_and(|failure| failure().is_some())
|
||||
}
|
||||
@@ -3132,7 +3130,6 @@ impl Registry {
|
||||
id: plugin.definition.id.clone(),
|
||||
target: plugin.definition.target().map(str::to_owned),
|
||||
source: plugin.source,
|
||||
// `slow` is a flag on `active` (4.14).
|
||||
slow: (status == Status::Active).then(|| self.monitor.report(&plugin.definition.id)).flatten(),
|
||||
status,
|
||||
active: plugin.active.is_some(),
|
||||
@@ -3424,7 +3421,6 @@ impl Registry {
|
||||
/// The `part` of every active registration in activation order, cloned so no borrow outlives the call.
|
||||
fn by_activation<T: Clone>(&self, part: impl Fn(&Registration) -> &Vec<T>) -> Vec<T> {
|
||||
let plugins = self.plugins.borrow();
|
||||
// A plugin that panicked contributes nothing (4.14): its claims give their slots back.
|
||||
let mut active: Vec<_> =
|
||||
plugins.iter().filter(|plugin| plugin.running()).filter_map(|plugin| plugin.active.as_ref()).collect();
|
||||
active.sort_by_key(|(order, _)| *order);
|
||||
|
||||
@@ -1025,11 +1025,8 @@ impl Loader {
|
||||
Some(Found::Build(identified))
|
||||
}
|
||||
|
||||
/// The one place that decides whether the library of `target`, at `file`, may be opened, before anything of it
|
||||
/// runs: a project's build waits for the user's approval (3.9), and the registry holds a build that crashed the
|
||||
/// client, every external one in safe mode, and every one in a client no parent guards (4.5). Returns the build's
|
||||
/// digest, bytes and raw quarantine to open, all read through one descriptor, or, when it is held or unchanged,
|
||||
/// whether the manager's list changed.
|
||||
/// Checks approval and crash policy before loading a native build. Returns the digest, bytes and quarantine from
|
||||
/// one descriptor; a held or unchanged build is not opened.
|
||||
fn admit(
|
||||
&self,
|
||||
host: &Rc<dyn Host>,
|
||||
@@ -1048,7 +1045,7 @@ impl Loader {
|
||||
};
|
||||
let unchanged = |digest: u64| self.seen.borrow().get(name).is_some_and(|seen| seen.digest == digest);
|
||||
let (digest, bytes, quarantine) = match target.project {
|
||||
// A project's build runs only once the user approved this artifact (3.9). Until then nothing of it is read
|
||||
// A project's build runs only once the user approved this artifact. Until then nothing of it is read
|
||||
// but its hash, nothing is opened, and it claims nothing. What is loaded is what was hashed. When it
|
||||
// cannot be identified, what ran from it stops and nothing is reported.
|
||||
true => {
|
||||
|
||||
@@ -43,7 +43,7 @@ pub const HOST_MINOR: u32 = ABI_MINOR;
|
||||
/// a reason, not as no plugin.
|
||||
const ENTRY_V1: &str = "opencode_plugin_v1";
|
||||
|
||||
/// What crossed the C ABI on this thread, counted outside any plugin and any mount (4.14, `work`).
|
||||
/// What crossed the C ABI on this thread, counted outside any plugin and any mount.
|
||||
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
|
||||
pub struct Crossed {
|
||||
/// Calls the host made into plugins.
|
||||
@@ -1345,9 +1345,8 @@ struct Guest {
|
||||
cancels: bool,
|
||||
}
|
||||
|
||||
/// However the guest goes, by a disposal or by the host dropping the registry, a failed instance is not destroyed:
|
||||
/// `destroy` would run its dispose callbacks, and a failed plugin is called no more (4.14). It is kept, as its library
|
||||
/// is (4.5).
|
||||
/// Keep failed instances and their libraries alive: calling `destroy` would execute the failed plugin’s disposal
|
||||
/// callbacks.
|
||||
impl Drop for Guest {
|
||||
fn drop(&mut self) {
|
||||
self.release();
|
||||
|
||||
@@ -392,7 +392,7 @@ fn lock<T>(mutex: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
|
||||
mutex.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
|
||||
}
|
||||
|
||||
/// The heap an idle VM of `sources` holds once its setup ran: what a plugin costs at rest (the spike's measure).
|
||||
/// The heap an idle VM of `sources` holds once its setup ran: what a plugin costs at rest.
|
||||
pub fn idle_memory(sources: &Sources) -> Result<usize, String> {
|
||||
let manifest = Manifest::parse(sources.text(MANIFEST)?)?;
|
||||
let compiled = Rc::new(vm::Compiled::new(sources, &manifest.id, &manifest.entry)?);
|
||||
|
||||
@@ -47,10 +47,9 @@ pub struct Limits {
|
||||
pub inbox: usize,
|
||||
/// Trees from the child the UI thread has not taken, before the reader stops reading (S2: 8).
|
||||
pub trees: usize,
|
||||
/// How long the oldest event may wait for its acknowledgement (4.3: 1 s).
|
||||
/// How long the oldest event may wait for its acknowledgement.
|
||||
pub ack: Duration,
|
||||
/// The same for a load or a setup, which may import a large module before it reads on: not a frame's event (4.4).
|
||||
/// Also for whatever waits on the JS host's own start, until its hello: Bun loading the host's modules.
|
||||
/// Handshake, load and setup timeout. These events may import modules before acknowledging.
|
||||
pub setup: Duration,
|
||||
/// The JS host's resident set (S2: a minimal Bun is 20 to 26 MiB; 58 MB a loaded one).
|
||||
pub memory: u64,
|
||||
|
||||
@@ -1103,7 +1103,7 @@ fn register(setup: &mut Setup<'_>, guest: &Rc<Guest>) {
|
||||
});
|
||||
let place =
|
||||
surface::Place { name: claim.name.clone(), at, palette: claim.palette, notify: claim.notify.clone() };
|
||||
// No `layout` crosses the pipe: no frame waits for the JS host (3.7). A scroll event reaches the handler as the
|
||||
// No `layout` crosses the pipe: no frame waits for the JS host. A scroll event reaches the handler as the
|
||||
// others do.
|
||||
let calls = behave::Calls {
|
||||
plugin: setup.id().to_owned(),
|
||||
|
||||
@@ -354,7 +354,7 @@ fn inherited(name: &std::ffi::OsStr) -> bool {
|
||||
|| name.starts_with("OPENCODE_")
|
||||
}
|
||||
|
||||
/// What crossed the pipe, counted outside any plugin and any mount (4.14, `work`).
|
||||
/// What crossed the pipe, counted outside any plugin and any mount.
|
||||
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
|
||||
pub struct Crossed {
|
||||
/// Messages and bytes the host sent.
|
||||
@@ -659,7 +659,7 @@ enum Blame {
|
||||
Plugin(String),
|
||||
}
|
||||
|
||||
/// A fault the next handler's message suffers on its way to the JS host (4.14's pipe operators), for the tests.
|
||||
/// Fault injected into the next handler message in transport tests.
|
||||
#[doc(hidden)]
|
||||
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
||||
pub enum Fault {
|
||||
@@ -2021,7 +2021,7 @@ impl Scripts {
|
||||
/// The JS host ended, hung, broke the protocol, was flooded, or went over its budget: it is ended with its process
|
||||
/// group. `blame` names whom: the work it said it started and did not finish (its plugin fails), a plugin that
|
||||
/// flooded it, or nobody (memory). Every other plugin is set up again on a new JS host, and its surfaces keep their
|
||||
/// last trees until new ones come; a restart resets every plugin's JS state, as the process is one (3.7). The calls
|
||||
/// last trees until new ones come; a restart resets every plugin's JS state, as the process is one. The calls
|
||||
/// the JS host received and did not start are sent again, in order, after the setups: they never ran. One it started
|
||||
/// and did not finish is not: it may have done what it does, so it is never run twice (at most once). Past the limit
|
||||
/// of ends, every plugin on it fails.
|
||||
|
||||
@@ -868,7 +868,7 @@ impl Surface {
|
||||
return;
|
||||
}
|
||||
// Only a keep the host does not hold is mended by a whole tree; any other refusal is the plugin's
|
||||
// error, and fails it at once (3.4).
|
||||
// error, and fails it at once.
|
||||
if !matches!(refused, Refused::Unknown(_) | Refused::Kept(_)) {
|
||||
drop(state);
|
||||
self.wipe();
|
||||
@@ -1092,7 +1092,6 @@ impl Surface {
|
||||
let focused =
|
||||
self.holder().map(|owner| owner.focused()).filter(|focused| focused.surface || focused.node.is_some());
|
||||
let mut state = self.state.borrow_mut();
|
||||
// Content past what the plugin may hold is not kept: a node that shows it is a placeholder (4.2).
|
||||
let (admitted, over) = admit_content(&self.plugin, &staged.given);
|
||||
let State { tree, content, last, dropped, .. } = &mut *state;
|
||||
let restyled = !tree.styled_in(theme);
|
||||
@@ -1490,8 +1489,7 @@ pub(crate) fn part_output(host: &dyn Host, part: &v2::PartRef) -> Option<String>
|
||||
found
|
||||
}
|
||||
|
||||
/// Whether `bytes` have the header of a PNG, GIF, JPEG or WebP image within one image's limits (4.2): what the host
|
||||
/// decodes at all.
|
||||
/// Checks the image header and per-image limits before decoding.
|
||||
pub fn within_bounds(bytes: &[u8]) -> bool {
|
||||
let limits = limits::get();
|
||||
crate::image::size(bytes).is_some_and(|(width, height)| {
|
||||
@@ -1499,8 +1497,7 @@ pub fn within_bounds(bytes: &[u8]) -> bool {
|
||||
})
|
||||
}
|
||||
|
||||
/// The size of the image `bytes` decode to, or `None` where an image node of them shows nothing ([`abi::Read::image_size`]):
|
||||
/// it decodes them, within one image's limits (4.2).
|
||||
/// Decodes within the image budget. Invalid or oversized input has no size.
|
||||
pub fn decoded_size(app: &App, bytes: &[u8]) -> Option<(u32, u32)> {
|
||||
match decode(app, bytes) {
|
||||
Picture::Ready(image) => image.info().ok().map(|info| (info.width, info.height)),
|
||||
@@ -1508,8 +1505,7 @@ pub fn decoded_size(app: &App, bytes: &[u8]) -> Option<(u32, u32)> {
|
||||
}
|
||||
}
|
||||
|
||||
/// The image `bytes` decode to in the frame, for [`decoded_size`]: within one image's limits (4.2), else the
|
||||
/// placeholder; bytes that are no image, or do not decode, show nothing.
|
||||
/// Oversized images get a placeholder; undecodable images show nothing.
|
||||
fn decode(app: &App, bytes: &[u8]) -> Picture {
|
||||
let Some((width, height)) = crate::image::size(bytes) else {
|
||||
log::warn!("an image node's bytes are not a PNG, GIF, JPEG or WebP image");
|
||||
@@ -1535,7 +1531,7 @@ fn decode(app: &App, bytes: &[u8]) -> Picture {
|
||||
}
|
||||
|
||||
/// Which content of `staged` plugin `plugin` may hold beside what it holds, in the order the view gave it: the bytes
|
||||
/// admitted, and the handles past its share or the total (4.2), which the host does not keep.
|
||||
/// admitted, and the handles past its share or the total, which the host does not keep.
|
||||
pub(crate) fn admit_content(plugin: &str, given: &HashMap<ContentRef, Arc<[u8]>>) -> (u64, HashSet<ContentRef>) {
|
||||
let mut room = limits::room(plugin, limits::Kind::Content, 0);
|
||||
let mut given: Vec<(&ContentRef, &Arc<[u8]>)> = given.iter().collect();
|
||||
|
||||
Reference in New Issue
Block a user