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

[strk at refractions.net]

On Thu, Apr 21, 2005 at 10:26:30AM -0700, Chris Hodgson wrote:
> Strk, here's my input for you...
> 
> It seems like every change that anyone wants to make right now is going 
> to break ABI, so I say start a new branch, and stop worrying about it.

ABI is gone already. But I do can stop worrying ;)

> You have already identified the best way to prevent further ABI breakage 
> - the "compatibility layer", and switching everything over to using it 
> will effectively be an API breakage - so you might as well fit the other 
> API-breaking changes into the same branch (exception throwing, etc.). If 
> you plan these changes carefully, it should be possible to limit future 
> API breakage, perhaps by adding new/alternative functions instead of 
> replacing/breaking existing ones.

I disagree on this, as people not willing to jump on the wrapper
can just recompile their client code w/out big hassles (it would
be nice to have some feedback on this with current CVS as some
inner classes changed API but none of the ones accessible including
geos.h). If we change exceptions - for example - postgis-1.0.0 won't
be able to show GEOS3 exception messages (but postgis-1.0.1 might - see
below).

> You might also want to think about what exactly the goals of GEOS are - 
> to continue to mirror JTS development, or to move away from the Java 
> roots and into a more optimized C++ implementation? I think that since 
> there now exists the GJC option for a direct JTS-to-C-compatible 
> compilation option, it makes more sense for GEOS to work towards being 
> more optimized for C++, while still sharing algorithm changes 
> back-and-forth with JTS.

I think this can be done breaking ABI and growing API.

> I hope that's useful input...

Yes! Thanks.

I'm currently working on porting the WKB parser from JTS.
That would be a step toward the "compatibility layer" with
long lived ABI. Target for next geos release (3.0.0) will
be mailny providing API-near-compatible performance
improvements and possibly the layer (but it depends on
time constraints wheter the latter will be possible - mainly
due to garbage collection).

The exception change is still on the plate. Just a couple of
explanatory words on the topic:

Resource limits hit conditions will still be thrown by the standard
c++ library, so client code willing to catch both standard library
AND geos exceptions would do something like:

	catch(GEOSException *e)
	{
		//print e->toString();
		delete e;
	}
	catch(std::exception &e)
	{
		//print e
	}

Making GEOSException derive from std::exception and thrown by
reference would be cought by the second block and client code
considering both would keep working (unless they do anything
special with GEOSExceptions other then printing them).

A side note: PostGIS up to 1.0.0 catches standard exceptions
cleanly but does not print them, which will hide exceptions from
GEOS in case of a switch. PostGIS 1.0.1 might easily make 
this possible, but older versions are out of reach.

Thanks also to Frank for his contribution,
I really appreciated it!

--strk;

> Chris
> 
> strk at refractions.net wrote:
> 
> >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;
> >_______________________________________________
> >geos-devel mailing list
> >geos-devel at geos.refractions.net
> >http://geos.refractions.net/mailman/listinfo/geos-devel
> > 
> >
> 
> _______________________________________________
> geos-devel mailing list
> geos-devel at geos.refractions.net
> http://geos.refractions.net/mailman/listinfo/geos-devel