Re: Building extensibility into an API

On Oct 27, 3:27 pm, Francis Johnson <spamt...@xxxxxxxxxxxxxxx> wrote:
I've been having a discussion with some folks here about the wisdom or
otherwise of "building extensibility into an API".

Consider your favorite function in one of your libraries, perhaps
void foo(int bar, char *baz);

Now maybe you think of some cool improvement to foo that you could make,
but this relies on being able to pass an additional parameter to foo.
You now have some unattractive choices:
1) change the signature of foo and break API compatability between
versions of the library
2) have a new function
foo_v2(int bar, char *baz, long double newparam);
and make foo a wrapper for foo_v2.
3) don't make the improvement.

Now, this dilemma would never have arisen if you'd "built extensibility
into the API" in the following way.

Each function you write takes an unused void * parameter. So foo starts
out as
void foo(int bar, char *baz, void *p);
and the last parameter should be NULL.

Now, consider extending the parameters of foo. You now use a
foo_v2_extra_params structure. Its first field encodes the additional
parameters, and the remaining fields are these parameters. Then version
2 of foo can do this:

void foo(int bar, char *baz, void *p)
{
/* define additional params as auto variables */
if(p)
/* process *p, set up extra args */
else
/* set additional params to defaults */
/* do stuff */

}

If foo improves again, the struct just gets enlarged, and the function
casts p appropriately before proceeding.

Have people here implemented something like this in the past? What do
you think of it as a solution to the "API extension" problem?

Microsoft likes to put the size of a structure argument into itself
as a version indicator. This has an advantage (for poor programmer)
of not having to have/use magic constants.

SOMESTUFF stuff;
ZeroMemory (&stuff, sizeof stuff);
stuff.cbSize = sizeof stuff;
/* ... */
CallFunctionExSoWhatIfItsExAlready (&stuff);

Because Microsoft cares.

Best regards,
Yevgen

.

Relevant Pages

  • Re: linking C++ functions in a C program
    ... contains one function named foo() which is compiled in C, ... Therefore, no matter how you classify bar(), this program ... void foo; ... guess the compiler can generate two references to foo, one adorned, ...
    (comp.lang.c)
  • Circular dependency - I think..
    ... The header file for FOO is composed of BAR, ... int GetFbk(); ... void ComputeTorquerCmd(); ...
    (comp.lang.cpp)
  • Re: is assignment atomic/thread safe?
    ... void foo() ... with one thread running foo() while another runs bar(). ... and thus no guarantees are made about _when_ any given piece of code will execute. ...
    (comp.lang.java.programmer)
  • Re: Building extensibility into an API
    ... otherwise of "building extensibility into an API". ... Now maybe you think of some cool improvement to foo that you could make, ... foo_v2(int bar, char *baz, long double newparam); ... Each function you write takes an unused void * parameter. ...
    (comp.lang.c)
  • Re: Library bug or my fault?
    ... compiled using ARM/Linux cross-compiler and run on an ARM9 target. ... void memcpy ... 29 void cp(const Foo *foo) ... 31 Bar bar; ...
    (comp.lang.c)