ruby-core@ruby-lang.org archive (unofficial mirror)
 help / color / mirror / Atom feed
* [ruby-core:120858] [Ruby master Feature#21107] Add a Ractor safety & shareability section to stdlib class docs
@ 2025-02-02  6:57 osyoyu (Daisuke Aritomo) via ruby-core
  0 siblings, 0 replies; only message in thread
From: osyoyu (Daisuke Aritomo) via ruby-core @ 2025-02-02  6:57 UTC (permalink / raw)
  To: ruby-core; +Cc: osyoyu (Daisuke Aritomo)

Issue #21107 has been reported by osyoyu (Daisuke Aritomo).

----------------------------------------
Feature #21107: Add a Ractor safety & shareability section to stdlib class docs
https://bugs.ruby-lang.org/issues/21107

* Author: osyoyu (Daisuke Aritomo)
* Status: Open
----------------------------------------
## 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.
```



-- 
https://bugs.ruby-lang.org/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/lists/ruby-core.ml.ruby-lang.org/

^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2025-02-02  6:58 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2025-02-02  6:57 [ruby-core:120858] [Ruby master Feature#21107] Add a Ractor safety & shareability section to stdlib class docs osyoyu (Daisuke Aritomo) via ruby-core

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).