[FEATURE] Coordinate original-object advisory locks across build clients #32

Closed
opened 2026-10-02 08:13:55 +02:00 by erikinkinen · 0 comments
Owner

Problem and motivation

Concurrent build tools require advisory exclusion in addition to exclusive lockfile creation. Cargo documents shared/exclusive cache locks and build-directory locks; Rust file locking retains an open-description lifetime. Git's documented create/write/rename lockfile flow is already covered by existing namespace operations. Exact imported source selection and guest tool execution remain separate deliverables.

Proposed behavior and scope

Implement process-owned and open-description-owned record locking, whole-file shared/exclusive/unlock operations, nonblocking conflict queries/acquisition and blocking acquisition through existing admitted descriptor/scope custody. Preserve complete signed offset/length and zero-length-to-future-EOF semantics, negative-length normalization, replacement/splitting/coalescing, shared-read compatibility and exclusive conflicts. Coordinate locks across realms selecting the same original native file; do not substitute mediator-local pathname tables.

Use original VFS candidate/provider identity and existing counted storage. Derive ownership from the authenticated scope or retained shared description, never an application PID, pathname, fd number or claimed inode. Process locks release on any corresponding descriptor close; description locks survive aliases until final close. Blocking waits retain native invocation custody, detect required deadlock cycles, respond to cancellation and wake from lock-state changes without request replay.

Authority, security and reliability

Advisory exclusion adds no content, namespace, process-control, wait endpoint or entropy grant. Require the original admitted object and appropriate read/write access. Keep complete object/scope/description generations through rename, unlink, cancellation and teardown. Refusals and capacity exhaustion precede mutation. Uncertain operations retain cleanup custody. Scope retirement and process death release their original lock/wait ownership; copied IDs cannot unlock another owner. No mandatory-I/O permission or UID-zero bypass is introduced.

Acceptance criteria

Checklist
  • Implement canonical range/type/command contracts and exact cap-free native and compatibility framing with complete preflight/correlation.
  • Implement cross-scope native lock arbitration, conflict observations, atomic range changes and actual counted storage exhaustion.
  • Implement original-caller blocking/wakeup, deadlock, signal/cancellation and crash/scope cleanup without replay or orphaned waiters.
  • Implement actual compatibility descriptor consumers and nonfinal/final close, replacement and alias lifetime for both ownership families.
  • Author independent malformed/authority/range/contention/lifetime controls and native multi-client/multi-realm filesystem workloads.
  • Complete documentation, inline rustdoc/missing_docs and source size/authority reviews, coherent signed publication and public tracking.

Alternatives and tradeoffs

A pathname or per-mediator lock map would fail rename/hardlink identity or cross-realm exclusion. The shared original VFS object boundary can coordinate native scopes while preserving provider custody and existing resource budgets. Whole-file locking can use the same interval machinery as description-owned record locks; its interaction policy must be documented. Do not infer imported-tool acceptance from these substrate controls. Choose no new retry/depth/range-count limits beyond actual counted storage and scalar representability.

Tracking and rollout

Coordinate filesystem semantics, temporary outputs, Posixd review, VFS review and phase completion. Derive implementation independently from the POSIX fcntl contract, Rust File documentation, Cargo cache-lock documentation and Git lockfile documentation; import no external implementation code. Tests, builds, lint, generated documentation, VM/profiler execution and CI observation remain deferred. Both full guest EriX generations and external Rust/LLVM guest rebuilding remain required.

Original-object advisory lock completion — 2 October 2026

Original provider-confirmed objects and retained scope/candidate generations determine ownership; descriptive PIDs, paths and fd numbers grant no authority.

Abandonment cleans readiness even if Commit never arrived.

Libc entry points, exact imported-tool selection, both full EriX guest generations and external Rust/LLVM guest rebuilding remain required.

Related records and contracts
Repository Links
posixd issue 32, advisory-locks.md
vfsd issue 25
## Problem and motivation Concurrent build tools require advisory exclusion in addition to exclusive lockfile creation. Cargo documents shared/exclusive cache locks and build-directory locks; Rust file locking retains an open-description lifetime. Git's documented create/write/rename lockfile flow is already covered by existing namespace operations. Exact imported source selection and guest tool execution remain separate deliverables. ## Proposed behavior and scope Implement process-owned and open-description-owned record locking, whole-file shared/exclusive/unlock operations, nonblocking conflict queries/acquisition and blocking acquisition through existing admitted descriptor/scope custody. Preserve complete signed offset/length and zero-length-to-future-EOF semantics, negative-length normalization, replacement/splitting/coalescing, shared-read compatibility and exclusive conflicts. Coordinate locks across realms selecting the same original native file; do not substitute mediator-local pathname tables. Use original VFS candidate/provider identity and existing counted storage. Derive ownership from the authenticated scope or retained shared description, never an application PID, pathname, fd number or claimed inode. Process locks release on any corresponding descriptor close; description locks survive aliases until final close. Blocking waits retain native invocation custody, detect required deadlock cycles, respond to cancellation and wake from lock-state changes without request replay. ## Authority, security and reliability Advisory exclusion adds no content, namespace, process-control, wait endpoint or entropy grant. Require the original admitted object and appropriate read/write access. Keep complete object/scope/description generations through rename, unlink, cancellation and teardown. Refusals and capacity exhaustion precede mutation. Uncertain operations retain cleanup custody. Scope retirement and process death release their original lock/wait ownership; copied IDs cannot unlock another owner. No mandatory-I/O permission or UID-zero bypass is introduced. ## Acceptance criteria <details> <summary>Checklist</summary> - [x] Implement canonical range/type/command contracts and exact cap-free native and compatibility framing with complete preflight/correlation. - [x] Implement cross-scope native lock arbitration, conflict observations, atomic range changes and actual counted storage exhaustion. - [x] Implement original-caller blocking/wakeup, deadlock, signal/cancellation and crash/scope cleanup without replay or orphaned waiters. - [x] Implement actual compatibility descriptor consumers and nonfinal/final close, replacement and alias lifetime for both ownership families. - [x] Author independent malformed/authority/range/contention/lifetime controls and native multi-client/multi-realm filesystem workloads. - [x] Complete documentation, inline rustdoc/missing_docs and source size/authority reviews, coherent signed publication and public tracking. </details> ## Alternatives and tradeoffs A pathname or per-mediator lock map would fail rename/hardlink identity or cross-realm exclusion. The shared original VFS object boundary can coordinate native scopes while preserving provider custody and existing resource budgets. Whole-file locking can use the same interval machinery as description-owned record locks; its interaction policy must be documented. Do not infer imported-tool acceptance from these substrate controls. Choose no new retry/depth/range-count limits beyond actual counted storage and scalar representability. ## Tracking and rollout Coordinate [filesystem semantics](https://git.erikinkinen.fi/erix/posixd/issues/2), [temporary outputs](https://git.erikinkinen.fi/erix/posixd/issues/30), [Posixd review](https://git.erikinkinen.fi/erix/posixd/pulls/5), [VFS review](https://git.erikinkinen.fi/erix/vfsd/pulls/3) and [phase completion](https://git.erikinkinen.fi/erix/integration/issues/65). Derive implementation independently from the [POSIX fcntl contract](https://pubs.opengroup.org/onlinepubs/9799919799/functions/fcntl.html), [Rust File documentation](https://doc.rust-lang.org/std/fs/struct.File.html), [Cargo cache-lock documentation](https://doc.rust-lang.org/stable/nightly-rustc/cargo/util/cache_lock/index.html) and [Git lockfile documentation](https://git-scm.com/docs/api-lockfile.html); import no external implementation code. Tests, builds, lint, generated documentation, VM/profiler execution and CI observation remain deferred. Both full guest EriX generations and external Rust/LLVM guest rebuilding remain required. ### Original-object advisory lock completion — 2 October 2026 Original provider-confirmed objects and retained scope/candidate generations determine ownership; descriptive PIDs, paths and fd numbers grant no authority. Abandonment cleans readiness even if Commit never arrived. Libc entry points, exact imported-tool selection, both full EriX guest generations and external Rust/LLVM guest rebuilding remain required. <details> <summary>Related records and contracts</summary> | Repository | Links | | --- | --- | | posixd | [issue 32](https://git.erikinkinen.fi/erix/posixd/issues/32), [advisory-locks.md](https://git.erikinkinen.fi/erix/posixd/src/branch/feature/posix-compat/docs/advisory-locks.md) | | vfsd | [issue 25](https://git.erikinkinen.fi/erix/vfsd/issues/25) | </details>
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:35:07 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/posixd#32
No description provided.