From: shyouhei@... Date: 2020-05-03T08:26:33+00:00 Subject: [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: