[GRASS-dev] G__ in public API

[Glynn Clements]

Martin Landa wrote:
> 2014-06-11 13:00 GMT+02:00 Glynn Clements <glynn at gclements.plus.com>:
> 
> > It's probably an exaggeration to say that G__ functions are "internal
> > use only". It's closer to "this is (probably) not the function you
> > should be using". Typically, it indicates a lower-level function which
> > is "primarily" for internal use.
> >
> > There does seem to be some excessive use of G__ names (e.g.
> > lib/gis/env.c). But I wouldn't go so far as to say that G__ names
> > should *never* be used for functions which are used externaly,
> > particularly if such use is limited to a few specialised modules.
> 
> sure, but there are not few...
> 
> $ grep 'G__' * -R --include=*.c | grep -v ^lib | cut -d: -f1 | cut -d
> '/' -f2 | sort | uniq | wc -l
> 40

Looking at which functions are used, and how often:

     36 G__getenv
     23 G__setenv
     15 G__mapset_permissions
      9 G__put_window
      8 G__freea
      8 G__alloca
      6 G__getenv2
      5 G__projection_name
      5 G__get_window
      3 G__write_timestamp
      3 G__temp_element
      3 G__ls
      2 G__tempfile
      2 G__switch_search_path
      1 G__mapset_permissions2
      1 G__make_mapset_element

In most cases, the double-underscore version is a lower-level function
which takes more arguments. The corresponding single-underscore
version obtains some of the parameters from the working environment or
hard-coded defaults.

The double-underscore versions could be renamed to indicate what they
don't do, e.g.

	G__getenv	-> G_getenv_no_error
	G__setenv	-> G_setenv_no_write
	G__tempfile	-> G_tempfile_for_pid
	G__ls		-> G_ls_raw

Some of them (e.g. G__mapset_permissions) don't have a
single-underscore version, but aren't intended to be used by normal
modules. The extra underscore could simply be removed.

G__freea and G__alloca aren't functions but macros, defined thus:

	#ifdef __GNUC__
	...
	# define G__alloca(n) alloca(n)
	# define G__freea(p)
	#else
	# define G__alloca(n) G_malloc(n)
	# define G__freea(p) G_free(p)
	#endif

In particular, G__alloca() can't be a function, as the pointer
returned by alloca() is only valid until the calling function returns
(it allocates space on the stack).

These could either keep the extra underscore or changed to
all-uppercase as per the normal macro convention (G_ALLOCA, G_FREEA).

Finally, there are a few cases (which won't show up in source code
analysis) where the single-underscore name is a macro which expands to
a call to a function with a double-underscore name, e.g.

	#define G_malloc(n)     G__malloc(__FILE__, __LINE__, (n))
	#define G_calloc(m, n)  G__calloc(__FILE__, __LINE__, (m), (n))
	#define G_realloc(p, n) G__realloc(__FILE__, __LINE__, (p), (n))

	#define G_gisinit(pgm) G__gisinit(GIS_H_VERSION, (pgm))
	#define G_no_gisinit() G__no_gisinit(GIS_H_VERSION)

The linkage database generated by tools/dep_tree2sql.sh will show the
double-underscore names.

-- 
Glynn Clements <glynn at gclements.plus.com>