Issue #16959 has been updated by Eregon (Benoit Daloze).


When APIs like this are used in the wild, for many years, the docs can state "private API" (well actually these docs don't, they just suggest using weakref.rb, which has its own issues) but it's simply not accurate anymore.

mustermann has been using ObjectSpace::WeakMap since 2016, and the "tool" gem before since 2014 or earlier: https://github.com/rkh/tool/issues/2.
There was a fallback with a Hash but that's been clearly incompatible in many subtle ways.

JRuby implemented ObjectSpace::WeakMap so that further made it "API any gem can use".

And indeed recently there has been a few improvements to ObjectSpace::WeakMap discussed on this tracker (#16035, #16038), which clearly shows this API is considered public.
And it was also mentioned as part of the 2.7 NEWS file: https://github.com/ruby/ruby/blob/master/doc/NEWS-2.7.0

The specs are reviewed by me during synchronization with upstream ruby/spec.
I think it makes perfect sense to add specs for ObjectSpace::WeakMap and e.g., other ObjectSpace features as long as >1 Ruby implementation implements them, and it's not specifically annotated as MRI-only (currently, that's only RubyVM).

---

So concretely, what problems do you see with adapting the documentation of ObjectSpace::WeakMap to mark it "non-private"?
Any issue in the API?
AFAIK the only problem is the documentation doesn't clearly mention what's weak.

----------------------------------------
Bug #16959: Weakmap has specs and third-party usage despite being a private API
https://bugs.ruby-lang.org/issues/16959#change-86145

* Author: headius (Charles Nutter)
* Status: Open
* Priority: Normal
* Backport: 2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: UNKNOWN
----------------------------------------
Weakmap is still described as an internal API, and the documentation points users at WeakRef as the official public API:

https://github.com/ruby/ruby/blob/1fb16dbb6e28b9f32f92554d29e646e088b21a98/gc.c#L11928-L11936

However there are now specs for its current set of features, even though those features have never been discussed or approved as a public API:

https://github.com/ruby/spec/tree/dd8437628a6f2de5b74b338d4960682bb1590a60/core/objectspace/weakmap

And we are starting to see it being used by the community:

* https://github.com/jruby/jruby/issues/6267
* https://github.com/rsim/oracle-enhanced/issues/2027 
* https://github.com/rails/rails/pull/39121

One of two things needs to happen:

* Weakmap is made a public API after some discussion. It would be an official public feature only in 2.8/3.0 or higher.
* The specs are be removed and Weakmap remains a private API not to be used by the community. I suspect the addition of the specs led to folks starting to use this private API.

(edit: The Rails PR was merged after the specs, but the change is actually a year old, as mentioned below. In any case there's plenty of in-the-wild uses of WeakMap that go back even further.)

Personally, I'm in much more in favor of making WeakRef support all the features necessary to implement Weakmap in pure Ruby, rather than the other way around:

https://bugs.ruby-lang.org/issues/6309

But whatever happens it needs to happen soon, since this use case is now a merged feature in Rails master.



-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>