Home

Awesome

go-geos

PkgGoDev

Package go-geos provides an interface to GEOS.

Install

$ go get github.com/twpayne/go-geos

You must also install the GEOS development headers and libraries. These are typically in the package libgeos-dev on Debian-like systems, geos-devel on RedHat-like systems, and geos in Homebrew.

Features

Memory management

go-geos objects live mostly on the C heap. go-geos sets finalizers on the objects it creates that free the associated C memory. However, the C heap is not visible to the Go runtime. The can result in significant memory pressure as memory is consumed by large, non-finalized geometries, of which the Go runtime is unaware. Consequently, if it is known that a geometry will no longer be used, it should be explicitly freed by calling its Destroy() method. Periodic calls to runtime.GC() can also help, but the Go runtime makes no guarantees about when or if finalizers will be called.

You can set a function to be called whenever a geometry's finalizer is invoked with the WithGeomFinalizeFunc option to NewContext(). This can be helpful for tracking down geometry leaks.

For more information, see the documentation for runtime.SetFinalizer() and this thread on golang-nuts.

Errors, exceptions, and panics

go-geos uses the stable GEOS C bindings. These bindings catch exceptions from the underlying C++ code and convert them to an integer return code. For normal geometry operations, go-geos panics whenever it encounters a GEOS return code indicating an error, rather than returning an error. Such panics will not occur if go-geos is used correctly. Panics will occur for invalid API calls, out-of-bounds access, or operations on invalid geometries. This behavior is similar to slice access in Go (out-of-bounds accesses panic) and keeps the API fluent. When parsing data, errors are expected so an error is returned.

Comparison with github.com/twpayne/go-geom

github.com/twpayne/go-geom is a pure Go library providing similar functionality to go-geos. The major differences are:

go-geos is a good fit if your program is short-lived (meaning you can ignore memory management), or you require the battle-tested geometry functions provided by GEOS and are willing to handle memory management manually. go-geom is recommended for long-running processes with less stringent geometry function requirements.

License

MIT