Feature #21107: Add a Ractor safety & shareability section to stdlib class docs

• Status: Open
• Assignee: -
• Target version: -

[osyoyu (Daisuke Aritomo)]

Proposal

Add a section describing Ractor safety and shareability for each stdlib class.

For example, a description for Array could look like:

== Ractor safety and shareability

An \Array is not Ractor shareable by default. It can be turned shareable if the following conditions are met:

- The \Array itself is frozen.
- All elements in the \Array are Ractor shareable as well.

Or, for Random:

== Ractor safety shareability

A \Random instance cannot be made Ractor shareable. This is because of its nature having a internal state.

However, Random.srand and Random.rand can be called inside Ractors. Use those if you just need a random number inside a Ractor.

Background

Currently, it is not so easy to know if a object is Ractor shareable or not.
While Ractor.shareable? exists, it is painful to test each object during programming. It does not provide information on why a object is not Ractor shareable, how it can be Ractor shareable, or if that is possible in the first place.

Having this kind of information would be very helpful when writing Ractor code. It will help programmers choose more Ractor-friendly data structures and system designs.

Including why the class is not Ractor-shareable could also promote efforts making the Ruby ecosystem more Ractor-compatible.

Appendix: The SAFETY section in Rust docs

The Rust language docs has a similar concept. All functions that are marked as unsafe are expected to have a SAFETY section in their documentation. The section should state why the function is unsafe, what preconditions shall be met before calling, and what can happen if those are not fulfilled.
https://std-dev-guide.rust-lang.org/policy/safety-comments.html

For example, documentation for std::vec::Vec.set_len states what preconditions the implementation expects, and provides examples for other safe ways.

Forces the length of the vector to new_len.

This is a low-level operation that maintains none of the normal invariants of the type. Normally changing the length of a vector is done using one of the safe operations instead, such as truncate, resize, extend, or clear.

Safety

- new_len must be less than or equal to capacity().
- The elements at old_len..new_len must be initialized.