Struct Refcount

pub struct Refcount(/* private fields */);

Atomic reference counter.

This type is conceptually an atomic integer, but provides saturation semantics compared to normal atomic integers. Values in the negative range when viewed as a signed integer are saturation (bad) values. For details about the saturation semantics, please refer to top of include/linux/refcount.h.

Wraps the kernel’s C refcount_t.

Implementations

impl Refcount

pub fn new(value: i32) -> Self

Construct a new Refcount from an initial value.

The initial value should be non-saturated.

pub fn as_atomic(&self) -> &Atomic<i32>

Get the underlying atomic counter that backs the refcount.

NOTE: Usage of this function is discouraged as it can circumvent the protections offered by refcount.h. If there is no way to achieve the result using APIs in refcount.h, then this function can be used. Otherwise consider adding a binding for the required API.

pub fn set(&self, value: i32)

Set a refcount’s value.

pub fn inc(&self)

Increment a refcount.

It will saturate if overflows and WARN. It will also WARN if the refcount is 0, as this represents a possible use-after-free condition.

Provides no memory ordering, it is assumed that caller already has a reference on the object.

pub fn dec(&self)

Decrement a refcount.

It will WARN on underflow and fail to decrement when saturated.

Provides release memory ordering, such that prior loads and stores are done before.

pub fn dec_and_test(&self) -> bool

Decrement a refcount and test if it is 0.

It will WARN on underflow and fail to decrement when saturated.

Provides release memory ordering, such that prior loads and stores are done before, and provides an acquire ordering on success such that memory deallocation must come after.

Returns true if the resulting refcount is 0, false otherwise.

Notes

A common pattern of using Refcount is to free memory when the reference count reaches zero. This means that the reference to Refcount could become invalid after calling this function. This is fine as long as the reference to Refcount is no longer used when this function returns false. It is not necessary to use raw pointers in this scenario, see https://github.com/rust-lang/rust/issues/55005.

Trait Implementations

impl Send for Refcount

impl Sync for Refcount