Module starnix_uapi::ownership

This crates introduces a framework to handle explicit ownership.

Explicit ownership is used for object that needs to be cleaned, but cannot use Drop because the release operation requires a context. For example, when using the rust types to ensures the locking order, taking a lock requires knowing what locks are already held at this point, and uses an explicit object to represent this. If the object needs to take a lock during the release operation, Drop cannot provide it.

An object that uses explicit ownership uses the Releasable trait. The user must calls the release method on it before it goes out of scope.

A shared object that used explicit ownership used the OwnedRef/WeakRef/TempRef containers. The meaning are the following:

• Object that owns the shared object use OwnedRef. They are responsible to call release before dropping the reference.
• Object that do not owned the shared object use WeakRef. This acts as a weak reference to the object. They can convert it to a strong reference using the upgrade method. The returned value is an Option<TempRef>. The TempRef allows access to the object. Because this doesn’t repsent ownership, the TempRef must not be kept, in particular, the user should not do any blocking operation while having a TempRef.

Modules

• internal

Macros

• release_after
  Macro that ensure the releasable is released with the given context after the body returns.
• release_on_error
  Macro that ensure the releasable is released with the given context if the body returns an error.

Structs

• DropGuard
• OwnedRef
  An owning reference to a shared owned object. Each instance must call release before being dropped. OwnedRef will panic on Drop in debug builds if it has not been released.
• ReleaseGuard
  A wrapper a round a Releasable object that will check, in test and when assertion are enabled, that the value has been released before being dropped.
• TempRef
  A temporary reference to a shared owned object. This permits access to the shared object, but will block any thread trying to release the last OwnedRef. As such, such reference must be released as soon as possible. In particular, one must not do any blocking operation while owning such a refeence.
• TempRefKey
  Wrapper around TempRef allowing to use it in a Set or as a key of a Map.
• WeakRef
  A weak reference to a shared owned object. The upgrade method try to build a TempRef from a WeakRef and will fail if there is no OwnedRef left.

Traits

• Releasable
  The base trait for explicit ownership. Any Releasable object must call release before being dropped.
• ReleasableByMut
  The base trait for explicit ownership. Any Releasable object must call release before being dropped.
• ReleasableByRef
  The base trait for explicit ownership. Any Releasable object must call release before being dropped.

Functions

• debug_assert_no_local_temp_ref
  Assert that no temp ref exist on the current thread. This is used before executing a blocking operation to ensure it will not prevent a OwnedRef release.