[ruby-core:98127] [Ruby master Misc#16803] Discussion: those internal macros reside in public API headers

Issue #16803 has been updated by shyouhei (Shyouhei Urabe).


Thank you for looking at the new macros/functions.

Eregon (Benoit Daloze) wrote in #note-3:
> I took a look, these look fine to me, they seem almost all about portability, except `RUBY3_ANYARGS_DISPATCH*`.

Yes.  ANYARGS related ones were explicitly converted to have RUBY3_* prefix, to make them something non-standard.  I don't think we want people to use them directly.

> I think most of those could even be public portability helper macros (with a different prefix then, like `RB_`), and they wouldn't be hard to support long term as MRI needs them anyway.

Or maybe they could be separated into different header-only library, like ccan.  I guess they are ruby-agnostic.

> For example, intuitively `ruby3_str_new_cstr()` sounds like a "the Ruby 3 way/the new C-API to create a Ruby String from a C String".
> But it's not, it's just an internal function and implementation detail.
> 
> I think the only issue here is that `ruby3_/RUBY3_` is fairly unclear, unless people read that comment.
> But I can easily imagine they might miss that comment due to looking at the middle of the file, or just ignore it.
> 
> I think we should consider other prefixes which might be clearer.
> `ruby3_/RUBY3_` sounds too much like "the new way to do things/the new C-API" when it's not.
> 
> Maybe `ruby_internal_/RUBY_INTERNAL_`?
> That's quite long, but those macros/functions are already long, and maybe a longer name is intuitively clearer it shouldn't be used in native extensions (plus, you know, there is "internal" in it).
> 
> Any thought on using `ruby_internal_/RUBY_INTERNAL_`?

I chose `RUBY3`/`ruby3` only to avoid jamming my fingers by typing some long names.  I feel for instance `ruby_internal_right_shift_is_arithmetic_p()` is a bit too long.  So while I don't stick at `3`, I would prefer something shorter than `_internal`.

Looking at other projects, Boost for instance uses `detail` for this purpose.  It seems there are other projects using `impl`.  What about those names, like `ruby_impl` or even, `rbimpl`?

----------------------------------------
Misc #16803: Discussion: those internal macros reside in public API headers
https://bugs.ruby-lang.org/issues/16803#change-85370

* Author: shyouhei (Shyouhei Urabe)
* Status: Open
* Priority: Normal
----------------------------------------
A while ago I merged https://github.com/ruby/ruby/pull/2991 ("Split ruby.h").  This seems working.  But the changeset raised several questions.

The biggest one relates to those newly publicised macros and inline functions.  For instance `RUBY3_STATIC_ASSERT` is a macro that expands to either `_Static_assert` (for C) or `static_assert` (for C++).  A similar mechanism has been implemented inside of our repository for a while.  The pull request moved the definition around to be visible outside.

#### Discussion #1 ####

Is it a good idea or a bad idea, to make them visible worldwide?

#### Discussion #2 ####

Why not publicise everything?  For instance debuggers could benefit from ruby internal symbols.

#### Discussion #3 ####

It is relatively hard for us to change public APIs (doing so could break 3rd party gems).  We don't want that happen for internal APIs.  How do we achieve future flexibility?



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

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