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