[ClusterLabs Developers] FYI: Proposal for pacemaker API direction

[Ken Gaillot]

Hi all,

Anyone who works on the Pacemaker code base might be interested in this
pull request from Chris Lumens:

 https://github.com/ClusterLabs/pacemaker/pull/1696

It's a simple idea but lays the groundwork for the future direction of
the pacemaker C API.

The immediate issue addressed is that we currently have an internal-
only library, libpengine, that is obscurely placed in the
daemons/schedulerd directory, whereas all our other libraries are under
the lib directory. Confusingly, there *is* a lib/pengine directory, but
it contains two other libraries, libpe_status and libpe_rules.

Another issue is that we haven't had a straightforward mechanism for
sharing code among pacemaker's command-line tools. So we wind up with
e.g. tools/fake_transition.c being compiled into multiple commands.

The solution is to promote libpengine to a general-purpose internal-
only library, and move it to lib.

Where this becomes interesting (if you're a pacemaker coder, anyway) is
that it would adopt some conventions for consistency:

* The library would be renamed libpacemaker-internal, with its code in
the lib/pacemaker-internal directory.

* It would be assigned the prefix "pcmki". All file names (and
eventually, function names) would start with "pcmki_", which will help
with trace logs. Header files would similarly start with "pcmki_" and
be kept under include/pcmki/. There would be a special header
include/pcmki.h that would include all the other headers, so tools etc.
would just have to include that one header.

We're starting with this library because it's not a public API, so we
can make all these changes without worrying about backward
compatibility. But the long-term plan would be:

* The current libcrmcluster library would remain separate, because it
requires the corosync libraries. It would be renamed libpacemaker-
cluster and be assigned the prefix "pcmkc".

* All other pacemaker libraries would be combined into a single
library, libpacemaker, with the prefix "pcmk".

This would greatly simplify the library setup, just three libraries for
public/cluster/private, and most applications that need the API would
simply be able to "#include <pacemaker/pcmk.h>".

Hopefully in conjunction, we would adopt some best practices like
avoiding global variables in the libraries, and hiding struct contents
via accessor functions to make it easier to change the implementation
without breaking backward compatibility.

This is all just a proposal, and we can use the pull request and this
thread to discuss any suggested changes to the scheme.
-- 
Ken Gaillot <kgaillot at redhat.com>