From mail at joeconway.com  Sun Aug 24 10:50:42 2003
From: mail at joeconway.com (Joe Conway)
Date: Sun Aug 24 18:57:45 2003
Subject: [Rd] declarations in non-exported headers and embedding R
Message-ID: <3F48ECE2.1090109@joeconway.com>

Hello,

I've been using R embedded in PL/R (R procedural language handler for 
PostgreSQL, http://www.joeconway.com/plr/) very successfully for several 
months now. A sincere "thank you" goes to the R development team for 
such a great product.

I have a question I'm hoping someone here can help me with. In order to 
get the required functionality out of PL/R, I've had to resort to using 
some defines and declarations that are only available in non-exported 
headers. There is precedent, of a sort, for most of what I've used in 
the tests/Embedding source. Below I'll present the header code I've 
used, where it comes from, why I've used it, and where I saw it used in 
tests/Embedding.

My question is whether there is equivalent exported functionality that 
I'm missing? Or if not, would a patch be accepted that moves this 
functionality to an exported header?

Thanks,

Joe

===========================================================
Here are the specifics:
-----------------------------------------------------------
 From non-exported header file ${R_HOME}/src/include/Parse.h
-----------------------------------------------------------
extern SEXP R_ParseVector(SEXP, int, int *);
#define PARSE_NULL			0
#define PARSE_OK			1
#define PARSE_INCOMPLETE	2
#define PARSE_ERROR			3
#define PARSE_EOF			4
-----------------------------------------------------------
 From non-exported header file ${R_HOME}/src/include/Defn.h
-----------------------------------------------------------
extern void R_PreserveObject(SEXP);
extern void R_ReleaseObject(SEXP);

Use:
-------------
The first time a PL/R function is called, the R function is built and 
parsed using R_ParseVector(), then cached for subsequent calls. Without 
R_PreserveObject() garbage collection destroys the object while PL/R is 
still trying to use it. R_ReleaseObject() is needed to release the 
object for garbage collection if the cached copy becomes invalid.

Note:
-------------
Similar use of R_ParseVector() found in
    ${R_HOME}/tests/Embedding/RParseEval.c
Similar use of R_PreserveObject() found in
    ${R_HOME}/tests/Embedding/Rshutdown.c


-------------------------------------------------------------
from non-exported header file ${R_HOME}/src/include/Startup.h
-------------------------------------------------------------
/* Startup Actions */
typedef enum {
     SA_NORESTORE,/* = 0 */
     SA_RESTORE,
     SA_DEFAULT,/* was === SA_RESTORE */
     SA_NOSAVE,
     SA_SAVE,
     SA_SAVEASK,
     SA_SUICIDE
} SA_TYPE;
-------------------------------------------------------------
from non-exported header file ${R_HOME}/src/unix/Runix.h
-------------------------------------------------------------
extern void Rstd_CleanUp(SA_TYPE saveact, int status, int runLast);

Use:
-------------
When the PostgreSQL backend process exits, Rstd_CleanUp() is called via 
registered onexit callback so that the embedded R interpreter can clean 
up (e.g. to remove the created Rtmp[pid] directory).

Note:
-------------
Similar use found in ${R_HOME}/tests/Embedding/Rerror.c


[Rd] declarations in non-exported headers and embedding R
Joe Conway