Support per-document read lock

cmd/fastbelt/generate.go

@@ -67,7 +67,7 @@ func runGenerateCLI(opts generateOptions) error {
 	if err != nil {
 		return err
 	}
-	if err := builder.Build(context.Background(), []*core.Document{document}, nil); err != nil {
+	if err := builder.Build(context.Background(), []*core.Document{document}); err != nil {
 		return err
 	}
 

document.go

@@ -7,6 +7,7 @@ package fastbelt
 import (
 	"strings"
 	"sync"
+	"sync/atomic"
 
 	"typefox.dev/fastbelt/textdoc"
 	"typefox.dev/lsp"
@@ -17,12 +18,15 @@ import (
 // For example, the Root node may be nil if the document has not been parsed yet.
 //
 // Access to the fields of Document should be synchronized using a [typefox.dev/fastbelt/workspace] Lock.
+// Readers admitted based on the document's build state (workspace Lock.ReadAt) may only access
+// the fields produced by the states they requested; later fields may still be under construction.
 // The document struct should never be copied after creation.
 type Document struct {
 	// URI identifies the document in the workspace.
 	URI URI
-	// State tracks which build phases already ran for this document.
-	State DocumentState
+	// state tracks which build phases already ran for this document.
+	// Access it through [Document.State] and [Document.SetState].
+	state atomic.Uint32
 	// Root is the AST root produced by parsing.
 	// It is nil until parsing succeeds.
 	Root AstNode
@@ -78,7 +82,6 @@ func NewDocument(textDoc textdoc.Handle) *Document {
 	uri := ParseURI(string(textDoc.URI()))
 	return &Document{
 		URI:                   uri,
-		State:                 0,
 		TextDoc:               textDoc,
 		Root:                  nil,
 		LocalSymbols:          nil,
@@ -108,6 +111,24 @@ func NewDocumentFromString(uri, languageId, content string) (*Document, error) {
 	return doc, nil
 }
 
+// State returns the build phases that have completed for this document.
+//
+// It is safe to call concurrently with a running build: the atomic load pairs
+// with [Document.SetState], so a caller that observes a state bit is
+// guaranteed to see all document data written by that build phase.
+func (d *Document) State() DocumentState {
+	return DocumentState(d.state.Load())
+}
+
+// SetState replaces the document's build state.
+//
+// Callers must hold the workspace write lock and must write all document data
+// belonging to a phase before setting its bit; the atomic store publishes that
+// data to concurrent [Document.State] readers.
+func (d *Document) SetState(state DocumentState) {
+	d.state.Store(uint32(state))
+}
+
 // DocumentState is a bitmask capturing the already completed build phases of a document.
 type DocumentState uint32
 
@@ -152,9 +173,9 @@ func (s DocumentState) String() string {
 	return strings.Join(flags, " | ")
 }
 
-// Has reports whether flag is set in s.
+// Has reports whether flag is set in s. If flag is a combination of multiple bits, Has reports whether all of them are set.
 func (s DocumentState) Has(flag DocumentState) bool {
-	return s&flag != 0
+	return s&flag == flag
 }
 
 // With returns s with flag set.

examples/statemachine/benchmark_test.go

@@ -54,8 +54,8 @@ func BenchmarkWorkspaceCycle(b *testing.B) {
 		}
 
 		start := time.Now()
-		lock.Write(context.Background(), func(ctx context.Context, downgrade func()) {
-			if err := builder.Build(ctx, docs, downgrade); err != nil {
+		lock.Write(context.Background(), func(ctx context.Context) {
+			if err := builder.Build(ctx, docs); err != nil {
 				b.Errorf("build failed: %v", err)
 			}
 		})
@@ -181,7 +181,7 @@ func BenchmarkLocalLinking(b *testing.B) {
 	docs := []*fastbelt.Document{doc}
 	builder := service.MustGet[workspace.Builder](srv)
 	// Prebuild the file - we will reset the references later
-	if err := builder.Build(b.Context(), docs, nil); err != nil {
+	if err := builder.Build(b.Context(), docs); err != nil {
 		b.Errorf("build failed: %v", err)
 	}
 	b.SetBytes(int64(len(content)))

examples/statemachine/builder_reset_test.go

@@ -48,7 +48,7 @@ func TestResetKeepsLocalSymbols(t *testing.T) {
 		t.Error("Reset kept ImportedSymbols although DocStateImportedSymbols was dropped")
 	}
 
-	if err := builder.Build(f.Ctx(), []*core.Document{doc.Document}, nil); err != nil {
+	if err := builder.Build(f.Ctx(), []*core.Document{doc.Document}); err != nil {
 		t.Fatalf("rebuild after reset failed: %v", err)
 	}
 	for _, ref := range doc.Document.References {

server/completion_contributor.go

@@ -97,6 +97,9 @@ func NewDefaultCompletionContributor() CompletionContributor {
 	return &DefaultCompletionContributor{}
 }
 
+// Ensure DefaultCompletionContributor implements CompletionContributor.
+var _ CompletionContributor = (*DefaultCompletionContributor)(nil)
+
 // CompletionForToken emits a default item only for keyword tokens that contains a letter or digit.
 // This prevents trivial punctuation tokens from appearing in the default completion list.
 func (*DefaultCompletionContributor) CompletionForToken(_ context.Context, tt *core.TokenType, _ int, _ ContributorContext, accept CompletionAcceptor) {

server/completion_provider.go

@@ -42,6 +42,17 @@ func NewDefaultCompletionProvider(sc *service.Container) CompletionProvider {
 	return &DefaultCompletionProvider{sc: sc}
 }
 
+// The default required state for completion is DocStateLinked, which has to be
+// satisfied across the whole workspace, because cross-references might require
+// complex scoping and linking to be fully resolved.
+func (s *DefaultCompletionProvider) RequiredState() (core.DocumentState, bool) {
+	return core.DocStateLinked, true
+}
+
+// Ensure that the default completion provider correctly implements the interfaces
+var _ DocumentStateRequirements = (*DefaultCompletionProvider)(nil)
+var _ CompletionProvider = (*DefaultCompletionProvider)(nil)
+
 // HandleCompletionRequest fulfils textDocument/completion. The flow is:
 //
 //  1. resolve doc + cursor offset;

server/completion_snippet.go

@@ -55,6 +55,9 @@ type DefaultSnippetRegistry struct {
 	snippets []SnippetTemplate
 }
 
+// Ensure DefaultSnippetRegistry implements SnippetRegistry.
+var _ SnippetRegistry = (*DefaultSnippetRegistry)(nil)
+
 // NewDefaultSnippetRegistry returns an empty registry.
 func NewDefaultSnippetRegistry() SnippetRegistry {
 	return &DefaultSnippetRegistry{}

server/completion_triggers.go

@@ -18,6 +18,9 @@ type CompletionTriggers interface {
 // DefaultCompletionTriggers returns nil - no auto-open characters.
 type DefaultCompletionTriggers struct{}
 
+// Ensure DefaultCompletionTriggers implements CompletionTriggers.
+var _ CompletionTriggers = (*DefaultCompletionTriggers)(nil)
+
 // NewDefaultCompletionTriggers returns the no-op trigger set.
 func NewDefaultCompletionTriggers() CompletionTriggers {
 	return &DefaultCompletionTriggers{}

server/definition_provider.go

@@ -25,10 +25,19 @@ type DefaultDefinitionProvider struct {
 	sc *service.Container
 }
 
+// Ensure the DefaultDefinitionProvider implements the expected interfaces.
+var _ DefinitionProvider = (*DefaultDefinitionProvider)(nil)
+var _ DocumentStateRequirements = (*DefaultDefinitionProvider)(nil)
+
 func NewDefaultDefinitionProvider(sc *service.Container) DefinitionProvider {
 	return &DefaultDefinitionProvider{sc: sc}
 }
 
+// The default definition provider requires the document in question to be linked.
+func (s *DefaultDefinitionProvider) RequiredState() (core.DocumentState, bool) {
+	return core.DocStateLinked, false
+}
+
 func (s *DefaultDefinitionProvider) HandleDefinitionRequest(ctx context.Context, params *lsp.DefinitionParams) ([]lsp.DefinitionLink, error) {
 	documentManager := service.MustGet[workspace.DocumentManager](s.sc)
 	uri := core.ParseURI(string(params.TextDocument.URI))

server/diagnostics_publisher.go

@@ -27,6 +27,9 @@ type DiagnosticsPublisher struct {
 	sc *service.Container
 }
 
+// Ensure DiagnosticsPublisher implements InitializeParticipant.
+var _ InitializeParticipant = (*DiagnosticsPublisher)(nil)
+
 // NewDiagnosticsPublisher creates a new instance of [DiagnosticsPublisher].
 func NewDiagnosticsPublisher(sc *service.Container) *DiagnosticsPublisher {
 	return &DiagnosticsPublisher{sc: sc}

server/document_highlight_provider.go

@@ -17,6 +17,10 @@ type DocumentHighlightProvider interface {
 	HandleDocumentHighlightRequest(ctx context.Context, params *lsp.DocumentHighlightParams) ([]lsp.DocumentHighlight, error)
 }
 
+// Ensure DefaultDocumentHighlightProvider implements the expected interfaces.
+var _ DocumentHighlightProvider = (*DefaultDocumentHighlightProvider)(nil)
+var _ DocumentStateRequirements = (*DefaultDocumentHighlightProvider)(nil)
+
 type DefaultDocumentHighlightProvider struct {
 	sc *service.Container
 }
@@ -25,6 +29,11 @@ func NewDefaultDocumentHighlightProvider(sc *service.Container) DocumentHighligh
 	return &DefaultDocumentHighlightProvider{sc: sc}
 }
 
+// The default document highlight provider requires the document in question to be linked.
+func (s *DefaultDocumentHighlightProvider) RequiredState() (core.DocumentState, bool) {
+	return core.DocStateLinked, false
+}
+
 func (s *DefaultDocumentHighlightProvider) HandleDocumentHighlightRequest(ctx context.Context, params *lsp.DocumentHighlightParams) ([]lsp.DocumentHighlight, error) {
 	documentManager := service.MustGet[workspace.DocumentManager](s.sc)
 	uri := core.ParseURI(string(params.TextDocument.URI))

server/document_symbol_provider.go

@@ -39,6 +39,14 @@ type DefaultDocumentSymbolProvider struct {
 	filter DocumentSymbolFilter
 }
 
+var _ DocumentSymbolProvider = (*DefaultDocumentSymbolProvider)(nil)
+var _ DocumentStateRequirements = (*DefaultDocumentSymbolProvider)(nil)
+
+// RequiredState indicates that the default document symbol provider requires the document to be parsed.
+func (p *DefaultDocumentSymbolProvider) RequiredState() (core.DocumentState, bool) {
+	return core.DocStateParsed, false
+}
+
 // NewDefaultDocumentSymbolProvider creates a provider using services from the container.
 func NewDefaultDocumentSymbolProvider(sc *service.Container) DocumentSymbolProvider {
 	return &DefaultDocumentSymbolProvider{

server/folding_range_provider.go

@@ -66,6 +66,15 @@ type DefaultFoldingRangeProvider struct {
 	filter FoldingRangeFilter
 }
 
+// Ensure DefaultFoldingRangeProvider implements the expected interfaces.
+var _ FoldingRangeProvider = (*DefaultFoldingRangeProvider)(nil)
+var _ DocumentStateRequirements = (*DefaultFoldingRangeProvider)(nil)
+
+// RequiredState indicates that the default folding range provider requires the document to be parsed.
+func (p *DefaultFoldingRangeProvider) RequiredState() (core.DocumentState, bool) {
+	return core.DocStateParsed, false
+}
+
 func NewDefaultFoldingRangeProvider(sc *service.Container) FoldingRangeProvider {
 	return &DefaultFoldingRangeProvider{
 		sc:     sc,

server/hover_provider.go

@@ -23,6 +23,15 @@ type DefaultHoverProvider struct {
 	sc *service.Container
 }
 
+// Ensure DefaultHoverProvider implements the expected interfaces.
+var _ HoverProvider = (*DefaultHoverProvider)(nil)
+var _ DocumentStateRequirements = (*DefaultHoverProvider)(nil)
+
+// RequiredState indicates that the default hover provider requires the document to be linked.
+func (s *DefaultHoverProvider) RequiredState() (core.DocumentState, bool) {
+	return core.DocStateLinked, false
+}
+
 func NewDefaultHoverProvider(sc *service.Container) HoverProvider {
 	return &DefaultHoverProvider{sc: sc}
 }

server/references_finder.go

@@ -33,6 +33,9 @@ type DefaultReferencesFinder struct {
 	sc *service.Container
 }
 
+// Ensure DefaultReferencesFinder implements the expected interfaces.
+var _ ReferencesFinder = (*DefaultReferencesFinder)(nil)
+
 func NewDefaultReferencesFinder(sc *service.Container) ReferencesFinder {
 	return &DefaultReferencesFinder{sc: sc}
 }

server/references_provider.go

@@ -23,6 +23,16 @@ type DefaultReferencesProvider struct {
 	sc *service.Container
 }
 
+// Ensure DefaultReferencesProvider implements the expected interfaces.
+var _ ReferencesProvider = (*DefaultReferencesProvider)(nil)
+var _ DocumentStateRequirements = (*DefaultReferencesProvider)(nil)
+
+// RequiredState indicates that the default references provider requires the workspace
+// to have reference information collected.
+func (rf *DefaultReferencesProvider) RequiredState() (core.DocumentState, bool) {
+	return core.DocStateReferences, true
+}
+
 func NewDefaultReferencesProvider(sc *service.Container) ReferencesProvider {
 	return &DefaultReferencesProvider{sc: sc}
 }

server/rename_provider.go

@@ -22,6 +22,16 @@ type DefaultRenameProvider struct {
 	sc *service.Container
 }
 
+// Ensure DefaultRenameProvider implements the expected interfaces.
+var _ RenameProvider = (*DefaultRenameProvider)(nil)
+var _ DocumentStateRequirements = (*DefaultRenameProvider)(nil)
+
+// RequiredState indicates that the default rename provider requires the workspace
+// to have reference information collected.
+func (rp *DefaultRenameProvider) RequiredState() (core.DocumentState, bool) {
+	return core.DocStateReferences, true
+}
+
 func NewDefaultRenameProvider(sc *service.Container) RenameProvider {
 	return &DefaultRenameProvider{sc: sc}
 }