Reorganize thread implementation to make a clearly defined

front-end/back-end interface.

From-SVN: r14309

gcc/objc/THREADS

@@ -119,6 +119,32 @@ that programs which rely upon the ObjC thread and mutex functions will
 compile and link correctly but attempting to create a thread or mutex will
 result in an error.
 
+It is questionable whether it is really necessary to have both a
+frontend and backend function for all available functionality.  On the
+one hand, it provides a clear, consistent differentiation between what
+is public and what is private with the downside of having the overhead
+of multiple functions calls.  For example, the function to have a thread
+yield the processor is objc_thread_yield; in the current implementation
+this produces a function call set:
+
+objc_thread_yield()  ->  __objc_thread_yield()  ->  system yield function
+
+This has two extra function calls over calling the platform specific function
+explicitly, but the issue is whether only the overhead of a single function
+is necessary.
+
+objc_thread_yield()  ->  system yield function
+
+This breaks the public/private dichotomy between the frontend/backend
+for the sake of efficiency.  It is possible to just use a preprocessor
+define so as to eliminate the extra function call:
+
+#define objc_thread_yield() __objc_thread_yield()
+
+This has the undesirable effect that if objc_thread_yield is actually
+turned into a function based upon future need; then ObjC programs which
+access the thread functions would need to be recompiled versus just
+being relinked.
  
 ******************************************************************************
 * Threads:
@@ -130,9 +156,19 @@ that the system implementation of malloc and free must be thread safe.
 If a system has multiple processors, the threads are configured for
 full parallel processing.
 
+* Backend initialization functions
+
+__objc_init_thread_system(void), int
+	Initialize the thread subsystem.  Called once by __objc_exec_class.
+	Return -1 if error otherwise return 0.
+
+__objc_close_thread_system(void), int
+	Closes the thread subsystem, not currently guaranteed to be called.
+	Return -1 if error otherwise return 0.
+
 *****
 * Frontend thread functions
-* User programs should use these thread functions.
+* User programs should use these functions.
 
 objc_thread_detach(SEL selector, id object, id argument), objc_thread_t
 	Creates and detaches a new thread.  The new thread starts by
@@ -173,15 +209,7 @@ objc_thread_get_data(void), void *
 * Backend thread functions
 * User programs should *NOT* directly call these functions.
 
-__objc_init_thread_system(void), int
-	Initialize the thread subsystem.  Called once by __objc_exec_class.
-	Return -1 if error otherwise return 0.
-
-__objc_fini_thread_system(void), int
-	Closes the thread subsystem, not currently guaranteed to be called.
-	Return -1 if error otherwise return 0.
-
-__objc_thread_create(void (*func)(void *arg), void *arg), objc_thread_t
+__objc_thread_detach(void (*func)(void *arg), void *arg), objc_thread_t
 	Spawns a new thread executing func, called by objc_thread_detach.
 	Return NULL if error otherwise return thread id.
 
@@ -222,36 +250,40 @@ last unlock on a mutex removes the system lock and allows other
 threads to access the mutex.
 
 *****
-* Frontend thread functions
-* User programs should use these thread functions.
+* Frontend mutex functions
+* User programs should use these functions.
 
 objc_mutex_allocate(void), objc_mutex_t
 	Allocates a new mutex.  Mutex is initially unlocked.
+	Return NULL if error otherwise return mutex pointer.
 
 objc_mutex_deallocate(objc_mutex_t mutex), int
 	Free a mutex.  Before freeing the mutex, makes sure that no
 	one else is using it.
+	Return -1 if error otherwise return 0.
 
 objc_mutex_lock(objc_mutex_t mutex), int
 	Locks a mutex.  As mentioned earlier, the same thread may call
 	this routine repeatedly.
+	Return -1 if error otherwise return 0.
 	
 objc_mutex_trylock(objc_mutex_t mutex), int
-	Attempts to lock a mutex.  Returns -1 if failed.  If lock on
-	mutex can be acquired then function operates exactly as
-	objc_mutex_lock.
+	Attempts to lock a mutex.  If lock on mutex can be acquired 
+	then function operates exactly as objc_mutex_lock.
+	Return -1 if failed to acquire lock otherwise return 0.
 
 objc_mutex_unlock(objc_mutex_t mutex), int
 	Unlocks the mutex by one level.  Other threads may not acquire
 	the mutex until this thread has released all locks on it.
+	Return -1 if error otherwise return 0.
 
 *****
-* Backend thread functions
+* Backend mutex functions
 * User programs should *NOT* directly call these functions.
 
-__objc_mutex_allocate(void), objc_mutex_t
+__objc_mutex_allocate(objc_mutex_t mutex), int
 	Allocates a new mutex, called by objc_mutex_allocate.
-	Return NULL if error otherwise return mutex pointer.
+	Return -1 if error otherwise return 0.
 
 __objc_mutex_deallocate(objc_mutex_t mutex), int
 	Free a mutex, called by objc_mutex_deallocate.
@@ -277,9 +309,10 @@ its owner (by thread id) and how many times it has been locked.  The
 last unlock on a mutex removes the system lock and allows other
 threads to access the mutex.
 
-*****
-* Frontend thread functions
-* User programs should use these thread functions.
+*
+* Frontend condition mutex functions
+* User programs should use these functions.
+*
 
 objc_condition_allocate(void), objc_condition_t 
 	Allocate a condition mutex.
@@ -291,6 +324,7 @@ objc_condition_deallocate(objc_condition_t condition), int
 	opportunity to wake.  It is legal to dealloc a condition only
 	if no other thread is/will be using it. Does NOT check for
 	other threads waiting but just wakes them up.
+	Return -1 if error otherwise return 0.
 
 objc_condition_wait(objc_condition_t condition, objc_mutex_t mutex), int
 	Wait on the condition unlocking the mutex until objc_condition_signal()
@@ -299,23 +333,27 @@ objc_condition_wait(objc_condition_t condition, objc_mutex_t mutex), int
 	here, for someone else can lock it and signal/broadcast the condition.
 	The mutex is used to lock access to the shared data that make up the
 	"condition" predicate.
+	Return -1 if error otherwise return 0.
 	
 objc_condition_broadcast(objc_condition_t condition), int
 	Wake up all threads waiting on this condition. It is recommended that 
 	the called would lock the same mutex as the threads in
 	objc_condition_wait before changing the "condition predicate"
 	and make this call and unlock it right away after this call.
+	Return -1 if error otherwise return 0.
 
 objc_condition_signal(objc_condition_t condition), int
 	Wake up one thread waiting on this condition.
+	Return -1 if error otherwise return 0.
 
-*****
-* Backend thread functions
+*
+* Backend condition mutex functions
 * User programs should *NOT* directly call these functions.
+*
 
-__objc_condition_allocate(void), objc_condition_t 
+__objc_condition_allocate(objc_condition_t condition), int
 	Allocate a condition mutex, called by objc_condition_allocate.
-	Return NULL if error otherwise return condition pointer.
+	Return -1 if error otherwise return 0.
 
 __objc_condition_deallocate(objc_condition_t condition), int
 	Deallocate a condition, called by objc_condition_deallocate.