(WIP)

[tmathern]

Changes in this pull request

Centralizes ManagedResources lifecycle plumbing: activation, consume-and-swap, and teardown to initialize objects (the managed resources holding a native handle) natively and handle their lifecycle.

Previously the lifecycle was driven by direct attribute assignment (self._handle = ptr, self._lifecycle_state = ACTIVE) repeated across subclasses. This change centralizes it behind four primitives and one hook:

• _activate(handle): take ownership of a validated non-null pointer and mark the resource active. Rejects null and double-activation, so a handle can't be activated twice and a closed resource can't be reopened.
• _swap_handle(new_handle): replace the handle after an FFI call consumed the old one and returned a replacement.
• _mark_consumed(): an FFI call took ownership with no replacement, release this object's own Python-side resources and mark it closed without freeing the native pointer.
• _wrap_native_handle(handle): build an instance around an already-owned pointer, bypassing init.
• _init_attrs(): subclass hook for attribute defaults, called by both init and _wrap_native_handle so an instance built around an existing handle can't be missing state the class reads.

Those are all private APIs for native handling (hence underscore in function name, using and calling them must be very explicit).

Note on fork safety: the owner PID is still stamped on all paths (including _wrap_native_handle), and the native free is skipped in a foreign process on all teardown paths (_mark_consumed, _cleanup_resources).

Checklist

• This PR represents a single feature, fix, or change.
• All applicable changes have been documented.
• Any TO DO items (or similar) have been entered as GitHub issues and the link to that issue has been included in a comment.