From ripley at stats.ox.ac.uk  Wed Nov 15 17:44:53 2006
From: ripley at stats.ox.ac.uk (Prof Brian Ripley)
Date: Wed, 15 Nov 2006 16:44:53 +0000 (GMT)
Subject: [Rd] Feature request: put NewEnvironment and R_NewhashedEnv
 into API
In-Reply-To: <m21wo4g1y1.fsf@ziti.local>
References: <m2ac2th35g.fsf@ziti.local>
	<Pine.LNX.4.64.0611150537070.2837@gannet.stats.ox.ac.uk>
	<m21wo4g1y1.fsf@ziti.local>
Message-ID: <Pine.LNX.4.64.0611151623540.5340@gannet.stats.ox.ac.uk>

On Wed, 15 Nov 2006, Seth Falcon wrote:

> Prof Brian Ripley <ripley at stats.ox.ac.uk> writes:
>> NewEnvironment is currently exposed as Rf_NewEnvironment.
>> R_NewHashedEnv is currrently hidden, but I'll unhide it.  It does not
>> need a further prefix.
>
> Thank you.  Could someone provide a bit more detail on how to
> determine if a given function in R's C code is exposed and/or public
> or not?
>
> Here's my current understanding after taking a look at Brian's patch
> r39907:
>
> A function can be hidden or not, but this is independent of whether the
> function is "sanctioned" as part of R's package API.  Functions that
> are not hidden can be used from package C code, but that doesn't
> answer whether they _should_ be used.

It is the intention that no entry point in the API is hidden, so any found 
would be a mistake (please report). All others will potentially be, and 
probably are unless they are used by a module or a standard package or 
some older package known to us.

[Hiding occurs in two places, by 'attribute_hidden' in the C source and 
the file src/gnuwin/Rdll.hide.]

> To determine if a function is public, look at the headers in
> R/src/include and refer to the README.

It may be better to look in the installed headers in R_HOME/include in an 
installed version.  I am not sure anyone aims to keep README fully up to 
date.

> Thus, NewEnvironment and R_NewHashedEnv, are both private since they are 
> declared in Defn.h. At present, one could call these function in package 
> code, since they are not hidden.

There's another layer: to be in the API they need to documented in R-exts.
There are many public but non-API entry points.

So:

API: documented in R-exts and in an installed header file

public: in an installed header file

private: visible on all systems but not in any installed header file

hidden: not visible on either Windows on a modern Unix in libR.so (or 
both) -- ulitmately you need to check R.dll and libR.so.

I try to avoid the 'should' word (some posters here are far too fond of 
telling us what 'R should do'): I believe what we say is that using 
non-API entry points is likely to lead to breakage without any warning.


-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595



[Rd] Feature request: put NewEnvironment and R_NewhashedEnv into API
Prof Brian Ripley