Plain C API design, the real world Kobayashi Maru test

I've done a few APIs similar in spirit to this one (and one similar in functionality, too), and I've found using a blend of a few of the mentioned methods to be pretty effective.

I start with the basics and implement everything as explicitly (read: type safe) as possible:

    struct bob_params {...}
    struct line_params {...}

    pdf_page_cmd_bob(bob_params *params) { ... }
    pdf_page_cmd_line(line_params *params) { ... }

Then, when that works and I want to add patterns, which are a superset, I'd add something that is literally a superset of those functions.

    enum pattern_type {
      patterntype_Bob,
      patterntype_Line,
    }

     struct pattern {
       pattern_type type;
       union {
         bob_params Bob;
         line_params Line;
       }
     }

     pdf_pattern_cmd(pattern *pattern) {
       switch (pattern->type) {
         case patterntype_Bob: /* do bob drawing a bunch of times, or whatever */ 
       }
     }

     // The pattern struct has a lot of different names (sum type, discriminated union, algebraic datatype, tagged union .. probably more), but the idea is the 'type' tag tells you which one of the union values to use.

I've tried everything and, as far as I can tell, this gets you the best of all worlds. It's pretty much as type-safe as things get in C. It's extremely flexible; you just mix the fundamentals together as you like when adding higher-order functions. It's fast; the compiler can see exactly what's going on, so you pay minimal runtime cost.

Yes, it's a bunch of typing to get the functions all spelled out, but it's really not that bad considering how easy/obvious the code actually is.

I use this pattern so much I actually wrote a little metaprogramming language that is capable of generating a lot of the boilerplate for you. Link in my bio, if anyone's interested in looking at it.

COM (Component Object Model) is compatible with C. It's still obviously C++ code being shoehorned into C by explicitly declaring the layout of the object (VTable member), but it does work. You get inheritance that way, and inter-module compatible cleanup. The downside is so much boilerplate code to declare the object, and the performance cost of virtual calls.

You don't necessarily need the complete COM system. For example, you could remove use of the Windows Registry, use of IDL files, remove the `QueryInterface` method, remove the use of GUIDs, remove the class factories (when just a simple 'create' function would do), remove Windows API functions related to cross-module memory management (not using `CoTaskAlloc`). Then it would be portable to systems that aren't Windows. One thing you can't remove is specifying a calling convention for the class methods, because C++ `__thiscall` is not compatible with C code on Windows.

Composition?

    typedef struct { /* ... */ } context;
    typedef struct {
      context ctx;
      /* ... */
    } foo_context;
    typedef struct {
      context ctx;
      /* ... */
    } bar_context;

    void some_general_method(context* ctx, int a, int b);
    void some_foo_specific_method(foo_context* foo_ctx, int c, int d);

    foo_context* foo_ctx;
    some_foo_specific_method(foo_ctx, 0, 0);
    some_general_method(&foo_ctx->ctx, 1, 1);

For checked downcasts, you could include an enum type tag inside `context` and have something like `foo_context* as_foo_context(context* ctx)` for downcasts, which, if `context` is at the beginning of `foo_context`, could just check the tag and cast the `ctx` pointer to `foo_context*` (or do a little pointer arithmetic if `context` is somewhere else in the containing struct). Return `NULL` (or assert) if the tag doesn't match.

What is not considered in the article is to replace pointers to pages and patterns with handles that are tagged indexes into internal arrays.

The big plus is the index tag allows to detect use after free and other memory safety bugs in wast majority of cases greatly improving memory safety.

If one then expose this handle as a generic typedef type over some integer type, then the API will be not type-safe, but the type mismatch will be detected very early.

Another option is to wrap the handle into separated structs for type safety. Then the caller will need to convert from specific handle for page, pattern etc. to the base handle when calling common draw operations. But that will be a simple operation like page.base or pattern.base, not MYLIB_PATTERN_TO_BASE(pattern). The drawback is that the caller will be able to construct wrong handles via struct initialization, but that is a big abuse and the type mismatch will still be detected at runtime.

This is a nice concrete example of a situation where inheritance is useful for program design.

I think i'd go for the "object oriented" approach, but with convenience functions to avoid explicit upcasts. Start with three types:

  cairo_t /* a generic context, could be a page or a pattern */
  cairo_page_t
  cairo_pattern_t

Functions only defined on pages take a page:

  void pdf_page_cmd_bob(cairo_page_t* ctx);

Functions defined on both take a generic context:

  void pdf_ctx_cmd_l(cairo_t* ctx, int x, int y);

Then you need some way to upcast from the child types to the parent (which would be implicit in C++ etc):

  cairo_t* pdf_page_to_ctx(cairo_page_t* ctx);
  cairo_t* pdf_pattern_to_ctx(cairo_pattern_t* ctx);

So a call looks like:

  pdf_ctx_cmd_l(pdf_page_to_ctx(page), 10, 20);

But we can generate this:

  void pdf_page_cmd_l(cairo_page_t* ctx, int x, int y) {
    pdf_ctx_cmd_l(pdf_page_to_ctx(ctx), x, y);
  }

Which lets users write this:

  pdf_page_cmd_l(page, 10, 20);

The convenience functions could even be macros. There would be no loss of type safety from using macros that way. There would need to be a lot of convenience functions or macros, but they are trivial, and so could be generated by a script (or another macro!).

I know it isn’t really appropriate to the spirit of the article, but it seems like in this case there is a right answer, and it’s “Fully separate object types” - it’s explicit, prevents errors, is complete, and while it requires a lot of typing to implement it doesn’t require much complexity.

API stability is THE #1 most important thing to get right.

I don’t care about the details of your API. I have worked with API’s that triggered a WTF every 5 secs. But I don’t care. I figure it out, build an abstraction on top that makes sense to me, and move on with far more important things.

So do what Linus does with Linux. Don’t f* break clients! Add a separate new API instead or expand the old API with additional entry points. Never ever deprecate anything in your API!

API developers that think it makes sense to break all clients, and force those clients to make changes, just because they wake up one day thinking that renaming FooBar to BarXk is a good idea, makes me want to throw my PC out of the window.

And who actually thought that marking things “deprecated” is a good idea? It is still an API change. With annoying warnings/errors added as a bonus.

Don’t. Do. It.

Use your brain to figure out how to accomplish the same task without breaking clients. The Linux guys can do it. So can you.

This seems perfect for _Generic.

https://en.cppreference.com/w/c/language/generic

> expose the full functionality of PDF directly

Is the objective to provide a PDF Swiss Army Knife? This requirement (if taken literally) precludes the API designer from enforcing much of a coherent mental model.

In terms of cheating, is one pattern format superior to the others? Could you pick one, only allow drawing commands for that one kind of pattern, then have the only method of rendering to the page take one or more of those patterns?

My ignorance of the PDF format is vast, and the question may be obviously absurd to anyone with the least bit of experience.

As an aside, this reminds me of the quagmire I have unsuccessfully wrestled with the various times I've tried to wrap my head around OpenGL

I've had a lot of ideas for cross-language libraries that would need a C API, and this issue always comes up. The idea I had several years ago---but never implemented, because most of the projects I'd use this for are in limbo because I never seem to finish anything---is an API with only one function, which takes JSON and returns JSON, possibly via JSON-RPC. Basically a library that pretends it's a remote service. Slow, yes, but not as slow as some alternatives, and it makes FFI setup with other languages easy.

Sometimes I wonder whether C (the ISO programming language) will ever diverge from C (the de facto FFI and ABI for all systems ever)

I expect no but I hope yes

I think the answer is function pointers.

This is a few paragraphs about the C API of cairo, postscript and pdf and it doesn't seem all that insightful.

I wish blog posts wouldn't use some random movie reference as clickbait when they could explain what their post is about instead.

> you can have functions like pdf_page_cmd_l(page, x, y)

oh, no, please don't.

just use c++ and you can have namespaces or classes to control visibility - there is no need to take on all the other c++ stuff if you don't want it.