Debian Codegraph @

doc/misc/design.rst

raw
1 ================
2 Design decisions
3 ================
4
5 * Generally follow `LuaJIT's ffi`_.
6
7 * Be explicit: almost no automatic conversions. Here is the set
8 of automatic conversions: the various C integer types are
9 automatically wrapped and unwrapped to regular applevel integers. The
10 type ``char`` might correspond to single-character strings instead;
11 for integer correspondence you would use ``signed char`` or ``unsigned
12 char``. We might also decide that ``const char *`` automatically maps
13 to strings; for cases where you don't want that, use ``char *``.
14
15 * Integers are not automatically converted when passed as vararg
16 arguments. You have to use explicitly ``ffi.new("int", 42)`` or
17 ``ffi.new("long", 42)`` to resolve the ambiguity. Floats would be
18 fine (varargs in C can only accept ``double``, not ``float``), but
19 there is again ambiguity between characters and strings. Even with
20 floats the result is a bit strange because passing a float works
21 but passing an integer not. I would fix this once and for all by
22 saying that varargs must *always* be a cdata (from ``ffi.new()``).
23 The possibly acceptable exception would be None (for ``NULL``).
24
25 * The internal class ``blob`` is used for raw-malloced data. You only
26 get a class that has internally a ``blob`` instance (or maybe is a
27 subclass of ``blob``) by calling ``ffi.new(struct-or-array-type)``.
28 The other cases, namely the cases where the type is a pointer or a
29 primitive, don't need a blob because it's not possible to take their
30 raw address.
31
32 * It would be possible to add a debug mode: when we cast ``struct foo``
33 to ``struct foo *`` or store it in some other struct, then we would
34 additionally record a weakref to the original ``struct foo`` blob.
35 If later we try to access the ``struct foo *`` but the weakref shows
36 that the blob was freed, we complain. This is a difference with
37 ctypes, which in these cases would store a strong reference and
38 keep the blob alive. "Explicit is better than implicit", so we ask
39 the user to keep a reference to the original blob alive as long as
40 it may be used (instead of doing the right things in 90% of the cases
41 but still crashing in the remaining 10%).
42
43 * LuaJIT uses ``struct foo &`` for a number of things, like for ``p[0]``
44 if ``p`` is a ``struct foo *``. I suppose it's not a bad idea at least
45 to have internally such types, even if you can't specify them through
46 pycparser. Basically ``struct foo &`` is a type that doesn't own a
47 blob, whereas ``struct foo`` is the type that does.
48
49 * LuaJIT uses ``int[?]`` which pycparser doesn't accept. I propose
50 instead to use ``int[]`` for the same purpose (its use is anyway quite
51 close to the C standard's use of ``int[]``).
52
53
54 .. _LuaJIT's ffi: https://luajit.org/ext_ffi.html