[openib-general] OpenSM/osm_log API: Use symbol versionsrather than polluting namespace

[Doug Ledford]

On Thu, 2006-09-07 at 09:22 +0300, Michael S. Tsirkin wrote:
> Quoting r. Doug Ledford <dledford at redhat.com>:
> > Subject: Re: [openib-general] OpenSM/osm_log API: Use symbol versionsrather than polluting namespace
> > 
> > On Wed, 2006-09-06 at 18:16 +0300, Michael S. Tsirkin wrote:
> > > Quoting r. Hal Rosenstock <halr at voltaire.com>:
> > > > Subject: Re: OpenSM/osm_log API: Use symbol versions rather than polluting namespace
> > > > 
> > > > On Wed, 2006-09-06 at 09:42, Michael S. Tsirkin wrote:
> > > > > Quoting r. Hal Rosenstock <halr at voltaire.com>:
> > > > > > Subject: OpenSM/osm_log API: Use symbol versions rather than polluting namespace
> > > > > > 
> > > > > > OpenSM/osm_log API: Rather than polluting the namespace with needless
> > > > > > symbols, use symbol versions and have a versioned osm_log_init rather
> > > > > > than adding osm_log_init_v2 as an additional API
> > > > > > 
> > > > > > This patch is intended to be applied to both trunk and 1.1 versions.
> > > > > > 
> > > > > > Signed-off-by: Doug Ledford <dledford at redhat.com>
> > > > > > Signed-off-by: Hal Rosenstock <halr at voltaire.com>
> > > > > 
> > > > > This preserves the ABI, but would this not break the API?
> > > > 
> > > > Yes, this patch changes the API (in a most trivial way).
> > > 
> > > So all users need to change code or they won't compile against the new
> > > library?
> > 
> > Yes, and that is the correct way to handle this change.
> 
> I disagree.
> 
> In my opinion, asking all users to add a parameter they don't care about is
> worse than having multiple functions with a convenient set of options.

Dude, you can't do that.

Ulrich Drepper, long time Cygnus/Red Hat employee, upstream maintainer
of glibc, and probably the most all around authoritative person I know
when it comes to open source library management, keeps most of the
papers he has delivered to different conventions on his web site:

http://people.redhat.com/drepper/

Amongst those papers are several best practices papers on shared library
design and maintenance.  Two things in particular jump out as reasons to
keep the list of exported symbols in a DSO to the absolute bare minimum:
1) every symbol in the DSO is part of the global symbol table for the
app, which has to be searched through during run time symbol resolution,
so the more symbols you have, the more dynamic linking slows down the
application (ever wondered why it takes from 20s to 1min to start
OpenOffice?  It's because of the proliferation of DSO symbol exports and
symbol table relocations and lookups in the OO libs) and 2) if you keep
the exported symbols at the bare minimum needed to implement the API, it
helps to free up the library to change and evolve behind the scenes
without requiring as many changes to linked applications, where as the
more you expose to the applications, the more likely you are to have to
change that exposed interface at some point in time.

What you just argued for is the opposite of both of those accepted and
commonly used practices.  Not only that, but since all the old code
*could* be made to work with the new API using nothing more than a macro
in a header file, to argue for an extra symbol export is *really* the
wrong thing to do.  It's violating those two best practices above when
you could achieve the same goal without violating either.

>   And if
> there is a low cost way to help apps compile without code change, I don't see
> why it makes sense to create work.

Dude, you can't do that either.  You have to keep the API clean.  If you
try to push the maintenance burden into the libraries instead of making
the apps carry their share of the maintenance, then the library just
ends up imploding under the impossible complexity of keeping all those
different API code bases working.  This particular issue certainly
wouldn't have been the end of the world, but when enough things like
this creep in over time, you'll eventually need to make a gen3 stack
because this one is unusable.  You have to put your foot down and just
say no on stuff like this.


> > APIs change.
> 
> APIs should not change with every release.

With a mature product, no.  This is hardly a mature product.


> > Any app you can build can compensate.
> 
> Sure it seems simple if you are RedHat and rebuild the whole OS.

OFED == whole stack == same thing.  If you are allowing some out of
stack software configuration issue to cause you as OFED maintainer to
put hacks into OFED, then you need to put your OFED interests in front
of your Mellanox interests when making OFED decisions.

> We are past code freeze. I agree with Hal that it might be hard to
> draw a line
> between a critical and a non-critical bugfix. However, an API change
> that
> 1. is purely cosmetical
> 2. requires code changes in dependent applications
> 3. is not uncontroversial
> is, for me, obviously beyond that line.

While I agree with the past code freeze and would support yanking the
entire log file truncation change for that reason, the preservation of a
clean API, proper library symbol versions, and DSO best practices are
far from "cosmetical".

-- 
Doug Ledford <dledford at redhat.com>
              GPG KeyID: CFBFF194
              http://people.redhat.com/dledford

Infiniband specific RPMs available at
              http://people.redhat.com/dledford/Infiniband
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://lists.openfabrics.org/pipermail/general/attachments/20060907/d5c6939c/attachment.sig>