On 12/21/18 11:01 AM, Benjamin Barenblat wrote:
I’d like to change the way the liburweb API appears to consumers.
[...] As I see it, there ought to be
four categories of functions:
1. functions that are public for FFI purposes,
2. functions that are used in compiled code but should never be called
by FFI libraries,
3. functions that are internal to the runtime but need to be called
across translation units, and
4. static functions.
That sounds like a reasonable categorization. I hadn't mentally
distinguished too much between categories 2 and 3, but otherwise this
system matches my thinking.
I think only public functions (category 1) should be listed in urweb.h.
Functions needed by compiled code but not available for the FFI
(category 2) should go in their own header file, and to emphasize their
internal nature, we shouldn’t install that header in /usr/include but
rather in /usr/share/urweb. Internal functions needed across translation
units (category 3) should be declared in headers that are only used
while compiling the runtime and not installed at all.
I could go along with that. My current model is that the manual lists
all category-1 functions, though I may have missed some that belong
there. As for physically separating categories across header files, I
see the benefit of more detail/encapsulation conveyed by
machine-processed documentation (headers). I also see the downside of
added complexity in compilation and use of the file system.
The major challenge here is figuring out exactly what the public API
should be. What functions and types should we expose to FFI consumers?
See last paragraph of my answer. I have always thought the manual
already answers this question, and it's a documentation bug if not.
But do FFI libraries really need to call, say,
uw_Basis_strlen, when there’s a perfectly reasonable strlen in libc that
does the same thing?
No, they shouldn't, and that's why I didn't list any 'uw_Basis_*'
functions in the manual. However, you picked a funny example, since
things have recently been getting interesting there, with support
(mostly by Fabrice Leal) for internationalization in the runtime
system! As a person unfamiliar with how all that business works, I
might indeed be tempted to call uw_Basis_strlen from C FFI code!
_______________________________________________
Ur mailing list
Ur@impredicative.com
http://www.impredicative.com/cgi-bin/mailman/listinfo/ur
