diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/libc_r/NOTES | 185 | ||||
| -rw-r--r-- | lib/libc_r/TODO | 16 |
2 files changed, 128 insertions, 73 deletions
diff --git a/lib/libc_r/NOTES b/lib/libc_r/NOTES index 25669e05d0b..39200fdb086 100644 --- a/lib/libc_r/NOTES +++ b/lib/libc_r/NOTES @@ -12,9 +12,9 @@ Sources . MIT pthreads (Chris Provenzano) - The test code in the TEST directory - I'm mainly tracking changes in FreeBSD's libc_r and integrating them - as I can. The major changes to Birrell's code involved making the - context switching a bit more architecture-independent. + I'm mainly tracking changes in FreeBSD's libc_r and integrating + them as I can. The major changes are outlined at the end of this + file. Standards @@ -22,110 +22,142 @@ Standards . Posix Threads[1] . Single Unix Specification[2] -Header files +Conformance - Only the absolutely required re-entrant functions have been added to - the C library interface headers in /usr/src/include. + Only the absolutely required re-entrant functions have been added + to the C library interface headers (in /usr/src/include). - The new functions are: - readdir_r() <dirent.h> - sigwait() <signal.h> - flockfile() <stdio.h> - ftrylockfile() <stdio.h> - funclockfile() <stdio.h> - getc_unlocked() <stdio.h> - getchar_unlocked() <stdio.h> - putc_unlocked() <stdio.h> - putchar_unlocked() <stdio.h> - rand_r() <stdlib.h> - strtok_r() <string.h> - asctime_r() <time.h> - ctime_r() <time.h> - gmtime_r() <time.h> - localtime_r() <time.h> + The conformance goals used were: minimal implementation; strict + conformance with standard; provide reasonable utility when standards + are spineless (e.g., our asynchronous cancel is eager even though + POSIX says async cancels may be acted upon at any time -- ie + never.) - The widely used, but non-standard, gethostbyname_r() needs thought. + The widely used, but non-standard, gethostbyname_r() has been + half-heartily added (but not prototyped in a header - see source + for details). Please contact me if you have pointers to + standards/comments about this function. - These functions are available even when not using the thread package; - i.e., they are also in the non-threaded libc.a. + Re-entrant functions added for the standards have also been made + available to libc (i.e. without the need to define _POSIX_THREADS). - See below why <sys/errno.h> has not been changed. +Change strategy in libc -Changes to libc sources - - The approach taken to making the libc functions re-entrant was to + The approach taken in making the libc functions re-entrant was to develop some macros that handle: . file locking . monitors (thread-shared data structure locking) . per-thread private data structure allocation - Macros were used to avoid copious amounts of #ifdef statements[3]. + These macros were used to avoid copious amounts of #ifdef + statements[3]. In the non-threaded libc, file locking and the monitors are no-ops; - the per-thread private data structures were previously declared static - and the macros maintain this. + the per-thread private data structures were previously declared + static and the macros maintain this. In the threaded libc_r, file locking is as per the FreeBSD file descriptor locking, and the monitors are pthread_mutex operations. - Per-thread private data structures use the pthread_specific functions - to dynamically allocate memory on their first use, initialising - them from the static (and hidden) per-compilation-unit data structures. + Per-thread private data structures use the pthread_specific + functions to dynamically allocate memory on their first use, + initialising them from the static (and hidden) per-compilation-unit + data structures. In this way, each thread appears to have its + very own private libc state. Errno - Unlike the FreeBSD and MIT pthreads package, errno is not a macro; - instead it is part of the per-thread context and saved and restored like - a register. This has several advantages over the errno-as-a-macro method: + Unlike the FreeBSD and MIT pthreads package, errno is not a macro + like __error(); instead it is part of the per-thread context: + saved and restored like a register. This has several advantages + over the errno-as-a-macro method: - The syscall/cerror code does not have to be re-written - Libraries compiled without thread support will still work - - Easier to port packages that use errno, but don't include <errno.h> + - Easier to port old packages that use errno, but don't include + <errno.h> to get the macro + - No need to go through all sources and find where errno is + used as a field name or formal parameter name. - The overhead of saving and restoring an integer was considered too tiny - to worry about in comparison to the huge penalty hit of handling a - signal and restoring the rest of a thread's context. + The overhead of saving and restoring an integer was considered + too tiny to worry about in comparison to the huge penalty hit of + handling a signal and restoring the rest of a thread's context. It has been pointed out that this technique will not work in a - mutiprocessor environment, and this is quite true. However the following - reasons are quite persuasive: + mutiprocessor environment, and this is quite true. However the + following reasons are quite persuasive: - OpenBSD does not do MP (yet) - - This (FreeBSD uthread) implementation will not work in an MP - environment anyway because _thread_run is not a cpu-local variable. - - There is a lot of coupling between binary ports and old libc and - other libraries that is quite a big headache to resolve in a - friendly manner. - -Compiler Support + - This (FreeBSD uthread) implementation will not work in an MP + environment anyway because _thread_run is not a cpu-local + variable. + - There is a lot of coupling between binary ports, the 'old' + libc and other standard libraries. It is predicted that it + will be a huge headache to come up with a scheme that when + someone tries to upgrade, everything won't break in a spectacular + fashion, leaving bits of crippled ports, executables and + shattered libraries everywhere. + +Compiler support The in-tree gcc had its config/openbsd.h modified to support a - `-pthread' switch. Using this switch defines _POSIX_THREADS for cpp, and - replaces the normal -lc linker option with -lc_r. + `-pthread' switch. Using this switch defines _POSIX_THREADS for + cpp, and replaces the normal -lc linker option with -lc_r. - The objective-C component was also made aware of posix threads, via - the configure switch --enable-threads=posix. + The objective-C component was also made aware of posix threads, + via the configure switch --enable-threads=posix. {This has not + been well tested though.} -Changes to FreeBSD uthreads +Debugger support + + The in-tree gdb has been augmented to recognise when a executable + linked with -lc_r is being debugged. All the documented gdb threads + commands will then work. (Except you can't resume/step execution + in a thread other than the 'current' one.) + + To get detailed state information, issue: - The following significant changes have been made to John Birrell's - uthreads implementation: + (gdb) call _thread_dump_info() - - the SIGINFO handler generates much more friendly output + This will show what mutexes, condvars or file locks each process + is waiting on. If you use _flockfile_debug() instead of flockfile() + in your programs, source code references will appear in here too. + (see <stdio.h>) + +Changes to FreeBSD uthreads + + Although this implementation tracks the FreeBSD libc_r tree to + a large extent, the following significant changes have been made + to John Birrell's uthreads implementation that have yet to appear + (or may never appear) in FreeBSD's implementation: + + - architecture independent code generalised and moved out of + #ifdef's[3] (now support for sparc, mips, m68k, powerpc added + to i386, alpha) + - the SIGINFO handler generates much more friendly/useful output + - an implementation of poll() {probably bogus, but X11 seems to + work} + - an implementation of pthread_cancel() + - an implementation of pthread_[gs]etscope() {bogus} + - removal of the freebsd's support for init(8) {i.e., pid == 1} Caveats - Not everything above is working right now: read the TODO file. + This library is not 100% standards compliant - yet. It is certainly + moving in that direction though. There are still some unresolved + isseues, and the interested reader is directed towards the TODO + file. Standard disclaimer - This software is made available by the author to the public for free - and "as is". All users of this free software are solely and entirely - responsible for their own choice and use of this software for their - own purposes. By using this software, each user agrees that the - author shall not be liable for damages of any kind in relation to - its use or performance. + This software is made available by the author to the public for + free and "as is". All users of this free software are solely + and entirely responsible for their own choice and use of this + software for their own purposes. By using this software, each + user agrees that the author shall not be liable for damages of + any kind in relation to its use or performance. - Some parts of this software bear a copyright. + Some parts of this software bear their own copyright which is + different to the above disclaimer. References @@ -133,11 +165,20 @@ References Portable Operating System Interface (POSIX) -- Part 1: System Application Program Interface (API) -- Ammendment 2: Threads Extension [C Language]. IEEE Standards, September 1994. - [2] T912, The Single UNIX(R) Specification, Version 2. The Open + [2] T912, The Single UNIX(R) Specification, Version 2. The Open Group, February 1997. http://www.opengroup.org/pubs/catalog/t912.htm - [3] #ifdef Considered Harmful, or Portability Experience with C News. - H. Spencer and G. Collyer, Proc. of the Summer 1992 USENIX Conference, - San Antionio, Texas, 1992. pp. 185-198 + [3] #ifdef Considered Harmful, or Portability Experience with C + News. H. Spencer and G. Collyer, Proc. of the Summer 1992 + USENIX Conference, San Antionio, Texas, 1992. pp. 185-198 + +Acknowledgements + + Lots of kudos to Chris Provenzano et al. for the original + MIT-pthreads implementation that I still read to get ideas; and + also to John Birrell and the other FreeBSD developers who + consistently write high quality code. The help rendered from the + OpenBSD developers was greatly appreciated - especially from + Todd Fries. David Leonard <leonard@csee.uq.edu.au> -$OpenBSD: NOTES,v 1.2 1999/01/10 22:50:07 d Exp $ +$OpenBSD: NOTES,v 1.3 1999/01/17 23:43:47 d Exp $ diff --git a/lib/libc_r/TODO b/lib/libc_r/TODO index 0516ae94d71..3d5147c9f83 100644 --- a/lib/libc_r/TODO +++ b/lib/libc_r/TODO @@ -1,6 +1,20 @@ This is a list of things that still need to be done: +* Add + pthread_condattr_[gs]etpshared() -- and add warn_references + pthread_mutexattr_[gs]etprioceiling() + pthread_mutexattr_[gs]etprotocol() + pthread_mutexattr_[gs]etpshared() + pthread_mutex_[gs]etprioceiling() + sched_setparam() + sched_setscheduler() + +* Add _warn_references to the schedprio stuff +* Quiz jb about pthread_llist_remove.. change name to _thread_llist_remove? + - what pthread_setprio() and pthread_yield() for? + - shouldn't pthread_yield() be marked depreciated? + * Add thread stuff to the other archs in libc/arch/; ie change some usages of ENTRY to SYSENTRY in some .S files and add the new macros to their SYS.h. @@ -36,4 +50,4 @@ This is a list of things that still need to be done: * Figure out what to do with the configuration system variables (_SC_*) that are defined by POSIX 1003.1c (at least update sysconf(3)) -$OpenBSD: TODO,v 1.5 1999/01/10 22:51:14 d Exp $ +$OpenBSD: TODO,v 1.6 1999/01/17 23:43:47 d Exp $ |