From: Richard Kenner Date: Wed, 25 Jun 1997 20:23:17 +0000 (-0400) Subject: Reorganize thread implementation to make a clearly defined X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=f15e9e7ef22cffbdff2f1792dfc0d539fdd26a01;p=gcc.git Reorganize thread implementation to make a clearly defined front-end/back-end interface. From-SVN: r14309 --- diff --git a/gcc/objc/THREADS b/gcc/objc/THREADS index 5c3a4d1a131..034cb5a6b81 100644 --- a/gcc/objc/THREADS +++ b/gcc/objc/THREADS @@ -119,7 +119,33 @@ 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.