[geos-devel] ABI/API status and future development thougths

[strk at refractions.net]

I just updated the NEWS file and made a simple
test to inspect compatibility between 2.1.1 and
current CVS.

Well, ABI is broken already. Probably due to
inlining of some functions aimed at improving
performance.

On the other hand, the part of API used by
postgis is still intact (ie. requires recompilation
but then works fine). Postgis uses about all of
Geometry methods and many CoordinateSequence methods.

With the help of ChangeLog I might attempt at taking
the ABI back to compatible with 2.1.1. That might allow
us to release a 2.1.2 slightly faster then 2.1.1 but not
significantly as inlines made the big difference.

Alternatively we can give the ABI break for granted and
go on with optimizzation continuing with inlines.

This is for ABI.

About API. Breaking that means you won't be able to build
old packages using GEOS using new relese of GEOS.
For example, postgis-1.0.0 won't be able to use a new GEOS
iff it will throw exceptions by ref instead of by pointers.
This is just an example, and is the wider one, as the GEOS
interface is pretty big and brokage can happen at different
levels of "deepness". For example current GEOS CVS has a
different interface on BufferSubgraph, but 'simple' clients
won't use BufferSubgraph directly, nor is its interface
documented (I had care to cut-down documentation specifically
for this purpose in previous releases). This means that simple
clients will continue to work with this change but more
complex ones will need to be modified to support new API and
introduce some kind of compile-time switch based on GEOS version
to support multiple GEOS interfaces.

Sorry if I'm being long and boring but I think having this written
helps everybody taking a decision. I'm bound to good quality but
I know the hassles of ever-changing interfaces (instability).

Whatever we decide to do I think a good approach would be providing
some form of simplified interface to GEOS for use by clients, aimed
at giving the hard-to-maintain stability of both API and ABI.
This could be a shared library shipped with GEOS and acting as
an 'adapter' between the always-moving GEOS lib and the client code
keeping the ->GEOS interface in sync with GEOS and the ->user interface
as stable as possible.

I've made a first implementation of such an adapter for JTS, providing
JTS access to C/C++ code in a stabler fashion (reduced API, abstract
datatype and garbage collector basically). I envision the GEOS
counterpart to follow that effort, althought garbage collection would be
harder to do (it's there for free with libgcj - the GNU java lib).

So what I'm saying is that next GEOS release could provide this wrapper
and client code willing to stop this annoyances could link against the
wrapper instead of against the main lib. One other advantages of this
would be that choice between GEOS and JTS would be a matter of a single
define to change function prefixes.

Implementation costs in this direction would be:

	- porting the WKB parser 
	- intergaring the boheme garbage collector

Enough noise, I hope someone will actually read this :P

Every contribution on the topic is highly apprieciated!

--strk;