cadrumo.application.user_profile.profile_pointer module

Reentrant transition authority for the active-profile pointer.

The core record IO owns strict parsing and atomic replacement. This application authority owns the canonical custody-root lock and is consequently the only owner that may advance the durable pointer transition revision.

exception ActiveProfilePointerTransactionError(message=None, *, context=None, translated_message=None)

Bases: CadrumoError

Reject invalid nesting or use outside live transaction ownership.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• translated_message (str | None)

Return type:

None

code

class ActiveProfilePointerTransaction(*, root, owner_pid, owner_thread_id)

Bases: object

Pointer observations and transitions under the canonical root lock.

Parameters:

• root (Path)

• owner_pid (int)

• owner_thread_id (int)

read()

Return the sole selection-plus-coordinate observation.

Return type:

BucketPointer

select(bucket_id)

Select bucket_id and advance once unless it is already selected.

Return type:

BucketPointer

Parameters:

bucket_id (str)

compare_and_select(*, expected, bucket_id)

Select only when the exact observed record remains current.

Return type:

BucketPointer

Parameters:

• expected (BucketPointer)

• bucket_id (str)

compare_and_restore(*, expected, captured)

Restore a prior selection without ever restoring its old revision.

Return type:

BucketPointer

Parameters:

• expected (BucketPointer)

• captured (BucketPointer)

clear()

Persist an absent tombstone unless the selection is already absent.

Return type:

BucketPointer

active_profile_pointer_transaction(root=None, *, root_lock=None)

Acquire or re-enter the active-profile pointer transaction.

Re-entry is valid only for the same canonical root, process, and thread. Nested use for another root and inherited ownership after fork fail closed. The outermost call waits only for the bounded timeout enforced by profile_custody_local_lock().

Parameters:

• root (Path | None) – Local storage root. The configured root is used when omitted.

• root_lock (ProfileCustodyRootLockPort | None) – Optional application-owned lock provider for dependency injection; the public custody provider is used by default.

Yields:

The same ActiveProfilePointerTransaction object for every valid nested acquisition.

Raises:

• ActiveProfilePointerTransactionError – If nested ownership targets a different root or was inherited from another process.

• LockAcquisitionError – If the custody root sidecar remains contended until the configured lock timeout expires.

Return type:

Generator[ActiveProfilePointerTransaction]

observe_active_profile_pointer(root=None)

Return one lock-scoped public pointer observation.

Purpose-specific application readers use this facade instead of opening a parallel core read path; core bootstrap remains the sole inner-layer exception because it cannot depend outward on this application owner.

Return type:

BucketPointer

Parameters:

root (Path | None)