Re: [Chicken-hackers] Chicken-hackers Digest, Vol 92, Issue 7

[Peter Bex]

On Sun, Jul 06, 2014 at 05:01:18PM -0300, Arthur Maciel wrote:
> Probably all my doubts are due to my ignorance about C and computer
> internals, but I would love to understand more the chicken.h file.
> (
> http://code.call-cc.org/cgi-bin/gitweb.cgi?p=chicken-core.git;a=blob;f=chicken.h;h=f5a103ee14314f7c679e01dd8e11c0404043791a;hb=HEAD
> )
> 
> I feel really ashamed to ask this, but as I want to contribute more to
> Chicken, it would help me a lot to know about these details:
> - Throughout the whole file I can't guess what is the meaning of some
> prefix or suffix letters in function names, like:
>     - C_truep(x): I suppose the "p" stands for "predicate" as in Common
> Lisp, right?

Correct.

>     - C_c_pointer(x): what does the "_c_" stand for?

I suppose it stands for "C pointer", like in the FFI where we have a
c-pointer foreign type.  This macro doesn't appear to be used though.

>     - C_c_pointer_nn(x): what about "nn"?

"Not null".  The macro just fetches the pointer, so it can only be used
in case the value isn't #f.

>     - C_fixnum_plus(n1, n2) vs. C_u_fixnum_plus(n1, n2): does the "_u_" on
> the second mean "unsigned"?

It means "unsafe".  These _u_ prefixed macros and functions don't do any
typechecking and will happily dereference invalid objects.

>     - C_ub_i_flonum_plus(x, y): what about "ub"? unsigned byte?

"Unboxed"; in other words, a plain flonum which isn't wrapped as a
Scheme object.  This isn't used at the moment (we used to have
boxing/unboxing support but it was broken so it was removed).

>     - C_a_i_flonum_plus(ptr, c, n1, n2) and C_a_i(a, n): what about "a" and
> "i"?

The "a" means it's allocating; it accepts a pointer at which it will
store the object and increment it.  The "i" is "inline", which means it
doesn't accept a continuation but just returns.

Unfortunately, these two rules are applied very inconsistently so the
absense of "i" or "a" does not necessarily mean it's a CPS function
or that it doesn't allocate.  I think we should do a big sweep of the
codebase one day to make this more consistent, and remove more unused
stuff.  However, this will potentially break a lot of code, so we'd
need to carefully build it so that it'll stay backwards-compatible.

Once this has been done it may be worthwhile to nail down the API and
actually document it.  Currently only bits and pieces of the API is
documented, on an ad-hoc basis.

>     - C_mpointer: the "m" stands for "memory"?

I guess so, not sure.

>     - C_mk_bool: "mk" stand for "make"?

Yeah, and that's a little inconsistent with everything else.  C_bool
or C_i_bool would be a more consistent name.

> - Lines 777 to 838: I suppose the code is used for CPS, but I'm not sure
> about it and I can't figure out why it is implemented that way and how it
> is used in practice.

It says so in the comments: it's an evil hack which expands to a
cascading set of function-type defining macros for various argument
counts, from C_proc0 to C_proc128.  Run it through cpp(1) if you'd like
to know the result of that weird thing.

This is needed for stupid technical reasons: We store everything as
a "typeless" C_word, and when a procedure is grabbed it's cast to the
correct C_procN type where N is the number of arguments it needs.
There's a similar hack in runtime.c's definition of C_do_apply which
contains the invocation.  If a C function is grabbed from the procedure
table the same thing happens but specialised for the known type.

> - Lines 876 to 909: although this excerpt starts with a comment about Clang
> and G++ limitations on statement expressions, all the hackery is only
> implemented when DEBUGBUILD is defined. I don't understand why. I also
> can't understand the code from 892 to 909, but I suppose I need more C
> knowledge to that.

I'm to blame for that mess.  It's truly evil C macrology.   I was hoping
the comment would clarify its intent: the C_check() macro is used for
low-level type assertions at runtime, in a DEBUGBUILD.  This is so ugly
it deserves to be killed with fire, but it's proven to be very effective
at catching low-level, long-hidden hidden bugs, so I think it's important
to keep it for all its ugliness.

Of course if someone can make this cleaner and more portable that would
be much appreciated.

> I thought about comments like this in chicken.h:
> /* "p" suffix (like in C_truep) stands for "predicate" as in Lisp
> tradition. See: http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node69.html
> */
> 
> The CPS and statement expressions could be elsewhere.

Never mind the statement expressions; those are for internal use only,
but they need to be in chicken.h because they get embedded in accessors
which are compiled into user code.

> What do you think? Is it worthy?

I'm not sure the code is the most useful place for that, but we can
perhaps add it to the "C interface" chapter in the manual.

Cheers,
Peter
-- 
http://www.more-magic.net