From 96ffe84edbd5259a00acc7fb7316c70ea5028434 Mon Sep 17 00:00:00 2001 From: Nathan Sobo Date: Mon, 23 Jan 2023 21:51:10 -0700 Subject: [PATCH] Document Buffer::reparse --- crates/language/src/buffer.rs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/crates/language/src/buffer.rs b/crates/language/src/buffer.rs index 110e10564c..3c382b83b6 100644 --- a/crates/language/src/buffer.rs +++ b/crates/language/src/buffer.rs @@ -802,6 +802,29 @@ impl Buffer { self.sync_parse_timeout = timeout; } + /// Called after an edit to synchronize the buffer's main parse tree with + /// the buffer's new underlying state. + /// + /// Locks the syntax map and interpolates the edits since the last reparse + /// into the foreground syntax tree. + /// + /// Then takes a stable snapshot of the syntax map before unlocking it. + /// The snapshot with the interpolated edits is sent to a background thread, + /// where we ask Tree-sitter to perform an incremental parse. + /// + /// Meanwhile, in the foreground, we block the main thread for up to 1ms + /// waiting on the parse to complete. As soon as it completes, we proceed + /// synchronously, unless a 1ms timeout elapses. + /// + /// If we time out waiting on the parse, we spawn a second task waiting + /// until the parse does complete and return with the interpolated tree still + /// in the foreground. When the background parse completes, call back into + /// the main thread and assign the foreground parse state. + /// + /// If the buffer or grammar changed since the start of the background parse, + /// initiate an additional reparse recursively. To avoid concurrent parses + /// for the same buffer, we only initiate a new parse if we are not already + /// parsing in the background. fn reparse(&mut self, cx: &mut ModelContext) { if self.parsing_in_background { return;