Documentation reentrancy

[Jeff Johnston]

Carl van Denzen wrote:
> I am working on a very simple application, but do not know what is the 
> best solution. The documentation is not clear enough (for me).
> 
>  From the mailing list, the preferred way is NOT to use the _xxxx_r 
> functions. Mention this preference in the docs.
> 
> The documentation phrase "Each function which uses the global reentrancy 
> structure uses the global variable _impure_ptr, which points to a 
> reentrancy structure." is confusing. Is there really a GLOBAL reentrancy 
> structure?
> 

Yes.  I guess it would be clearer to call it the default reentrancy 
structure that is of global-scope.  It is used by functions that have
both a regular and _r form.  The regular form of the function calls the 
_r version, passing the default reentrancy structure "or" if 
__DYNAMIC_REENTRANCY__ is set to true, it calls the function 
__getreent() to get a reentrancy structure which is then passed to the 
_r version.

This leads to the following choices:

1. With no threading, just let functions use the default reentrancy
    struct (i.e. do nothing and don't worry about calling _r routines).
2. Call _r routines only and manually pass an appropriate reentrancy
    struct (one allocated per thread).
3. Update the _impure_ptr manually at thread switches and call the
    regular forms of functions (i.e. don't worry about calling _r
    suffixed functions).
4. Set the __DYNAMIC_REENT__ flag for the platform and
    provide a __getreent() function that returns a unique reentrancy
    struct for the current running thread.  Call regular forms
    of functions.

> An improvement to the documentation would be an addition to choice 2 
> (which I think is the preferred choice): "The global _impure_ptr should 
> be set to point to the thread-dependent _reent at every thread switch by 
> the OS".
>

Actually, I would say choice 4 is the preferred choice for threaded
newlib.

> Cheers,
> 
> Carl
>