1# 2# CDDL HEADER START 3# 4# The contents of this file are subject to the terms of the 5# Common Development and Distribution License (the "License"). 6# You may not use this file except in compliance with the License. 7# 8# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9# or http://www.opensolaris.org/os/licensing. 10# See the License for the specific language governing permissions 11# and limitations under the License. 12# 13# When distributing Covered Code, include this CDDL HEADER in each 14# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15# If applicable, add the following below this CDDL HEADER, with the 16# fields enclosed by brackets "[]" replaced with your own identifying 17# information: Portions Copyright [yyyy] [name of copyright owner] 18# 19# CDDL HEADER END 20# 21# 22# Copyright 2006 Sun Microsystems, Inc. All rights reserved. 23# Use is subject to license terms. 24# 25# ident "%Z%%M% %I% %E% SMI" 26# 27 28The Solaris Process Model Unification project: 29 PSARC/2002/117 Solaris Process Model Unification 30 4470917 Solaris Process Model Unification 31folded libthread into libc and has led to some fundamental changes 32in the rules by which code in libc must be developed and maintained. 33 34All code in libc must be both MT-Safe and Fork-Safe 35and where possible (almost everywhere), Async-Signal-Safe. 36 37To this end, the following rules should be followed: 38 39Almost all internal libc locks (mutexes and read-write locks) 40should be acquired and released via these interfaces: 41 42 mutex_t some_lock = DEFAULTMUTEX; 43 44 lmutex_lock(&some_lock); 45 ... do something critical ... 46 lmutex_unlock(&some_lock); 47 48 rwlock_t some_rw_lock = DEFAULTRWLOCK; 49 50 lrw_rdlock(&some_rw_lock); 51 ... multiple threads can do something ... 52 lrw_unlock(&some_rw_lock); 53 54 lrw_wrlock(&some_rw_lock); 55 ... only one thread can do something ... 56 lrw_unlock(&some_rw_lock); 57 58The above l* versions of the mutex and rwlock interfaces do more 59than the ordinary interfaces: They define critical regions in 60which the calling thread cannot be suspended (making the region 61fork-safe) and in which the calling thread has all signals deferred 62(making the region async-signal-safe). 63 64However, certain rules apply to the code within these critical regions: 65 66 - The code must be of guaranteed short duration; no calls 67 to interfaces that might block indefinitely are allowed. 68 This means no calls into stdio or syslog() and no calls 69 to cond_wait() unless there is a guarantee of an almost- 70 immediate call to cond_signal() or cond_broadcast() 71 from elsewhere. 72 73 - The code cannot call any non-l* synchronization 74 primitives (mutex_lock(), _private_mutex_lock(), 75 rw_wrlock(), rw_rdlock(), sema_wait(), etc.) 76 77 - The code cannot call any functions outside of libc, 78 including application callbacks and functions from 79 dlopen()ed objects, such as those in the I18N code. 80 81 - Because malloc(), calloc(), realloc(), and free() 82 are designed to be interposed upon, they fall into 83 the previous case of prohibition. None of these can 84 be called by a thread while in a critical region. 85 86There is a private memory allocator for use internally to libc. 87It cannot be interposed upon and it is safe to use while in 88a critical region (or for that matter while not in a critical 89region; it is async-signal-safe and fork-safe): 90 91 void *lmalloc(size_t); 92 void lfree(void *, size_t); 93 94 void *libc_malloc(size_t); 95 void *libc_realloc(void *, size_t); 96 char *libc_strdup(const char *); 97 void libc_free(void *); 98 99lmalloc() and lfree() are the basic interfaces. The libc_*() 100variants are built on top of lmalloc()/lfree() but they have 101the same interface signatures as the corresponding functions 102without the 'libc_' prefix. lmalloc() and libc_malloc() 103return zeroed memory blocks. Note that lmalloc()/lfree() 104require the caller to remember the size parameter passed 105to lmalloc() and to pass the same value to lfree(). 106 107Memory allocated by lmalloc() can only be freed by lfree(). 108Memory allocated by libc_malloc(), libc_realloc(), or libc_strdup() 109can only be freed by libc_free(). Never pass such allocated 110memory out of libc if the caller of libc is expected to free it. 111 112lmalloc()/lfree() is a small and simple power of two allocator. 113Do not use it as a general-purpose allocator. Be kind to it. 114 115There is a special mutual exclusion interface that exists for 116cases, like code in the I18N interfaces, where mutual exclusion 117is required but the above rules cannot be followed: 118 119 int fork_lock_enter(const char *); 120 void fork_lock_exit(void); 121 122fork_lock_enter() does triple-duty. Not only does it serialize 123calls to fork() and forkall(), but it also serializes calls to 124thr_suspend() (fork() and forkall() also suspend other threads), 125and furthermore it serializes I18N calls to functions in other 126dlopen()ed L10N objects that might be calling malloc()/free(). 127Use it in general like this: 128 129 (void) fork_lock_enter(NULL); 130 ... serialized; do something that might call malloc ... 131 fork_lock_exit(); 132 133The 'const char *' argument to fork_lock_enter() should always 134be NULL except for two special cases: 135 - When called from fork() or forkall() 136 - When called from pthread_atfork() 137This enforces the prohibition against calling fork() or pthread_atfork() 138from a pthread_atfork()-registered fork handler function while a fork() 139prologue or epilogue is in progress. If _THREAD_ERROR_DETECTION is set 140to 1 or 2 in the environment, such cases will draw a nasty message and 141will dump core if _THREAD_ERROR_DETECTION=2. fork_lock_enter() returns 142non-zero only if it is called from a fork handler. This is of interest 143only to callers that have to do something about this condition; the 144return value should be ignored in all other cases (fork_lock_enter() 145never actually fails). 146 147It is an error to call fork_lock_enter() while in a critical region 148(that is, while holding any internal libc lock). 149 150On return from fork_lock_enter(), no internal libc locks are held 151but a flag has been set to cause other callers of fork_lock_enter() 152to delay (via _cond_wait()) until fork_lock_exit() is called. 153 154These are the rules to follow for memory allocation: 155 156 - If a function acquires an internal libc lock or is called while 157 an internal libc lock is held: 158 159 * The malloc family cannot be used. 160 161 * lmalloc or libc_malloc should be used. The memory must 162 be released by lfree or libc_free, respectively. 163 164 * lfree takes an argument to tell the size of the releasing 165 memory. If the function does not know the size at the 166 releasing point, libc_malloc and libc_free should be used. 167 168 * As the memory allocated by lmalloc or libc_malloc needs 169 to be released by lfree or libc_free and these are internal 170 to libc, they cannot be used to allocate memory that might 171 be released by application code outside libc. 172 173 * If the memory allocation by malloc() cannot be avoided and 174 the scalability of the function does not matter much, the 175 function can be serialized with fork_lock_enter() instead 176 of lmutex_lock(). 177 178 * If the memory allocation by malloc() cannot be avoided and 179 the scalability of the function does matter, another 180 implementation of the function will be necessary. 181 182In a DEBUG build of libc: 183 make THREAD_DEBUG=-DTHREAD_DEBUG install 184many of these rules are enforced by ASSERT() statements scattered about 185in the libc sources. This is the default mode for building libc when 186a DEBUG nightly build is performed. 187 188----- 189 190Some i18n code cannot be distributed as open source. To enable the rest of 191libc to be distributed as open source, those i18n files now live in a 192separate libc_i18n directory. Those source files are position-independently 193compiled and are archived into the libc_i18n.a library. The libc_i18n.a 194archive library is installed into the $(ROOTFS_LIBDIR) and 195$(ROOTFS_LIBDIR64) directories. During link phase, libc.so.1 links with 196libc_i18n.a in the proto area. Therefore, the build of the libc_i18n tree 197needs to be done before the build of the libc tree. Also the compilation 198conditions such as the setting of CFLAGS and CPPFLAGS for the libc_i18n 199stuff need to be compatible with the ones for the libc stuff. Whenever 200changes that affect the compilation conditions of libc occur, the changes 201should be propagated to libc_i18n. 202 203----- 204 205The putback of the project: 206 6416832 libaio and librt can and should be folded into libc 207introduced several libc-private locking interfaces: 208 void sig_mutex_lock(mutex_t *); 209 void sig_mutex_unlock(mutex_t *); 210 int sig_mutex_trylock(mutex_t *); 211 int sig_cond_wait(cond_t *, mutex_t *); 212 int sig_cond_reltimedwait(cond_t *, mutex_t *, const timespec_t *); 213which are declared in both "thr_uberdata.h" and "mtlib.h". 214 215They are used in specialized code in libc, like the asynchronous i/o code. 216Unlike the lmutex_lock() and lmutex_unlock() interfaces described above, 217these interfaces do not define critical regions, but signals are 218deferred while locks acquired by these functions are held, making 219their use be async-signal safe. Calls to malloc(), calloc(), realloc(), 220and free() are permissible while holding such locks. 221 222These interfaces were brought over from code in the former libaio 223and librt and are necessary because, where they are used, the code 224must execute potentially long-term waits and must be cancelable. 225sig_cond_wait() and sig_cond_reltimedwait() are cancellation points. 226 227These interfaces are available for other uses inside libc, as 228the need arises. (There is no need if the code does not perform 229long-term waits.) Just follow a few rules to be self-consistent: 230 - Don't mix calls to mutex_[un]lock(), lmutex_[un]lock() and 231 sig_mutex_[un]lock() on the same mutex. 232 - Don't call cond_wait() with a mutex acquired by sig_mutex_lock(); 233 call sig_cond_wait() or sig_cond_reltimedwait(). 234 - Use pthread_cleanup_push() and pthread_cleanup_pop() to make 235 your code cancellation-safe. 236 - The sig_*() interfaces are not in themselves fork-safe. 237 You have to employ other logic to make your code fork-safe. 238 See the tail of postfork1_child() for examples. 239