Bitmap allocator documentation.

[Loren James Rittle]

In article <1079086454.1387.14.camel@localhost.localdomain>,
Dhruv Matani<dhruvbird@HotPOP.com> writes:

> But after reading it seems not so clear to me when I'm supposed to use
> the macro and when the function, vaguely, it seems that I should be
> using the macro to protect veriable declarations, and the function to
> protect the actual locking of the mutex? However after looking at
> mt_allocator.h, I could see something like:
> #if defined __GTHREAD
> 	if (__gthread_active_p())
> 	//...

Well, of course, __gthread_active_p() itself is a __gthread* function
and thus must be guarded by __GTHREAD protection. ;-)

Everyone here agrees that gthr.h is a horrible abstraction layer for
threading...  However, it covers almost everything and a less horrible
layer would not do so. ;-)

> So is this protected by the macro or the function?

In case it is still not clear, some things get protected by both.
Both, using the idiom above, cover some functions calls.
Just the macro for data allocations, e.g. __gthread_mutex_t .
Ah, and note that some __gthread functions internally
check __gthread_active_p (__gthread_mutex_lock/unlock do).

> I could not find any documentation on gthreads, so if there is a place
> please let me know.

gcc/gthr.h and gcc/gthr-posix.h are the only source of comment
documentation to which I'm aware.  It is how I learned the API.

> However, peeking into the headers reveals that __gthread_active_p() just
> compares the address of a function with zero. I guess this is done to
> check the existence of the function in the code or something?

> What does it do exactly?

Many modern ELF systems can weak link the thread library.  Solaris,
Linux and FreeBSD all do.  If a program links against the thread
library but doesn't actually use pthread_create, etc; then gthr (for
POSIX) assumes that no threads other than main() are ever to be
present.

> There are a few things remaining as you have mentioned, and I'd like to
> list them out. If you have anything else in mind or I may have missed
> something out, please let me know.

> 1. Some variables still do not conform to the C++STYLE menioned in the
> document.

You got close enough for an ext/ header so I let it slide.

> 2. Some functions are made public unnecessarily. I will make sure that
> the scoping is correct.

> 3. The __GTHREADS issue that you have pointed out.

The maintainers have to get cranky over some things.

> 4. In the test-suite file, 4 macros are repeated (copy-paste error!).

5. you wanted to do native asm for various platforms of interest.

> I'll work on them and have a patch ready as soon as the gthreads issue
> is sorted out.

In light of internal use of __gthread_active_p() to reduce mutex
overhead for single-threaded cases by gthr.h itself on platforms
supporting WEAK symbols; you are done until there is extra tuning you
could do if you knew no threads existed.  The mt_allocator could
profit by doing so.  Sorry, if I raised a red herring, my main concern
was killing any advice that library users should directly touch the
__GTHREAD macro.  They should never have to touch it anymore.

Regards,
Loren