Skip to content

Rename AtomicPtr::fetch_ptr_{add,sub} to AtomicPtr::fetch_{add,sub} #126

Closed
@WaffleLapkin

Description

@WaffleLapkin

Proposal

Problem statement

AtomicPtr has unstable methods that allow mutating it like other atomic types:

impl<T> AtomicPtr<T> {
    pub fn fetch_ptr_add(&self, val: usize, order: Ordering) -> *mut T;
    pub fn fetch_ptr_sub(&self, val: usize, order: Ordering) -> *mut T;

    pub fn fetch_byte_add(&self, val: usize, order: Ordering) -> *mut T;
    pub fn fetch_byte_sub(&self, val: usize, order: Ordering) -> *mut T;

    pub fn fetch_or(&self, val: usize, order: Ordering) -> *mut T;
    pub fn fetch_and(&self, val: usize, order: Ordering) -> *mut T;
    pub fn fetch_xor(&self, val: usize, order: Ordering) -> *mut T;
}

These methods were added in order to remove some int2ptr casts (as part of the strict provenance initiative) that were forced because AtomicPtr did not have these APIs and AtomicUsize was used instead.

fetch_ptr_add and fetch_ptr_sub names are confusing and inconsistent:

  • ptr implies that the second argument is a pointer (like in case of sub_ptr for example), but it isn't
  • pointer::{add,sub} don't have the ptr part
  • the ptr was meant to suggest that these methods work in units of T (as opposed to fetch_byte_add), but it is already the default for pointers

Motivation, use-cases

The motivation is to make the naming less confusing, more consistent and easier to understand.

The search for fetch_(add|sub)\(.+\) as \* in public repositories doesn't yield many results, so I'm assuming using AtomicUsize as AtomicPtr with fetch_{add,sub} is not a common practice and we don't have almost any data of the use cases.

I do not know if this is because using AtomicUsize as AtomicPtr is not nice or if this is because fetch_add for pointers is not that useful.

Solution sketches

I propose just dropping _ptr part, renaming the methods to fetch_add and fetch_sub.

An alternative would be to come out with a better naming, however it would still be inconsistent with pointer methods (and I couldn't come out with anything which makes sense).

Additionally we should provide good documentation that clearly states (with examples) how these methods work.

Links and related work

What happens now?

This issue is part of the libs-api team API change proposal process. Once this issue is filed the libs-api team will review open proposals in its weekly meeting. You should receive feedback within a week or two.

Metadata

Metadata

Assignees

No one assigned

    Labels

    T-libs-apiapi-change-proposalA proposal to add or alter unstable APIs in the standard libraries

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions