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:
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
* 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.
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.
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.
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()
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.
projects / gcc.git / commitdiff