lib/libc/locale/DESIGN.xlocale

   1 $FreeBSD: head/lib/libc/locale/DESIGN.xlocale 227753 2011-11-20 14:45:42Z theraven $
   2
   3 Design of xlocale
   4 =================
   5
   6 The xlocale APIs come from Darwin, although a subset is now part of POSIX 2008.
   7 They fall into two broad categories:
   8
   9 - Manipulation of per-thread locales (POSIX)
  10 - Locale-aware functions taking an explicit locale argument (Darwin)
  11
  12 This document describes the implementation of these APIs for FreeBSD.
  13
  14 Goals
  15 -----
  16
  17 The overall goal of this implementation is to be compatible with the Darwin
  18 version.  Additionally, it should include minimal changes to the existing
  19 locale code.  A lot of the existing locale code originates with 4BSD or earlier
  20 and has had over a decade of testing.  Replacing this code, unless absolutely
  21 necessary, gives us the potential for more bugs without much benefit.
  22
  23 With this in mind, various libc-private functions have been modified to take a
  24 locale_t parameter.  This causes a compiler error if they are accidentally
  25 called without a locale.  This approach was taken, rather than adding _l
  26 variants of these functions, to make it harder for accidental uses of the
  27 global-locale versions to slip in.
  28
  29 Locale Objects
  30 --------------
  31
  32 A locale is encapsulated in a `locale_t`, which is an opaque type: a pointer to
  33 a `struct _xlocale`.  The name `_xlocale` is unfortunate, as it does not fit
  34 well with existing conventions, but is used because this is the name the Darwin
  35 implementation gives to this structure and so may be used by existing (bad) code.
  36
  37 This structure should include all of the information corresponding to a locale.
  38 A locale_t is almost immutable after creation.  There are no functions that modify it,
  39 and it can therefore be used without locking.  It is the responsibility of the
  40 caller to ensure that a locale is not deallocated during a call that uses it.
  41
  42 Each locale contains a number of components, one for each of the categories
  43 supported by `setlocale()`.  These are likewise immutable after creation.  This
  44 differs from the Darwin implementation, which includes a deprecated
  45 `setinvalidrune()` function that can modify the rune locale.
  46
  47 The exception to these mutability rules is a set of `mbstate_t` flags stored
  48 with each locale.  These are used by various functions that previously had a
  49 static local `mbstate_t` variable.
  50
  51 The components are reference counted, and so can be aliased between locale
  52 objects.  This makes copying locales very cheap.
  53
  54 The Global Locale
  55 -----------------
  56
  57 All locales and locale components are reference counted.  The global locale,
  58 however, is special.  It, and all of its components, are static and so no
  59 malloc() memory is required when using a single locale.
  60
  61 This means that threads using the global locale are subject to the same
  62 constraints as with the pre-xlocale libc.  Calls to any locale-aware functions
  63 in threads using the global locale, while modifying the global locale, have
  64 undefined behaviour.
  65
  66 Because of this, we have to ensure that we always copy the components of the
  67 global locale, rather than alias them.
  68
  69 It would be cleaner to simply remove the special treatment of the global locale
  70 and have a locale_t lazily allocated for the global context.  This would cost a
  71 little more `malloc()` memory, so is not done in the initial version.
  72
  73 Caching
  74 -------
  75
  76 The existing locale implementation included several ad-hoc caching layers.
  77 None of these were thread safe.  Caching is only really of use for supporting
  78 the pattern where the locale is briefly changed to something and then changed
  79 back.
  80
  81 The current xlocale implementation removes the caching entirely.  This pattern
  82 is not one that should be encouraged.  If you need to make some calls with a
  83 modified locale, then you should use the _l suffix versions of the calls,
  84 rather than switch the global locale.  If you do need to temporarily switch the
  85 locale and then switch it back, `uselocale()` provides a way of doing this very
  86 easily: It returns the old locale, which can then be passed to a subsequent
  87 call to `uselocale()` to restore it, without the need to load any locale data
  88 from the disk.
  89
  90 If, in the future, it is determined that caching is beneficial, it can be added
  91 quite easily in xlocale.c.  Given, however, that any locale-aware call is going
  92 to be a preparation for presenting data to the user, and so is invariably going
  93 to be part of an I/O operation, this seems like a case of premature
  94 optimisation.
  95
  96 localeconv
  97 ----------
  98
  99 The `localeconv()` function is an exception to the immutable-after-creation
 100 rule.  In the classic implementation, this function returns a pointer to some
 101 global storage, which is initialised with the data from the current locale.
 102 This is not possible in a multithreaded environment, with multiple locales.
 103
 104 Instead, each locale contains a `struct lconv` that is lazily initialised on
 105 calls to `localeconv()`.  This is not protected by any locking, however this is
 106 still safe on any machine where word-sized stores are atomic: two concurrent
 107 calls will write the same data into the structure.
 108
 109 Explicit Locale Calls
 110 ---------------------
 111
 112 A large number of functions have been modified to take an explicit `locale_t`
 113 parameter.  The old APIs are then reimplemented with a call to `__get_locale()`
 114 to supply the `locale_t` parameter.  This is in line with the Darwin public
 115 APIs, but also simplifies the modifications to these functions.  The
 116 `__get_locale()` function is now the only way to access the current locale
 117 within libc.  All of the old globals have gone, so there is now a linker error
 118 if any functions attempt to use them.
 119
 120 The ctype.h functions are a little different.  These are not implemented in
 121 terms of their locale-aware versions, for performance reasons.  Each of these
 122 is implemented as a short inline function.
 123
 124 Differences to Darwin APIs
 125 --------------------------
 126
 127 `strtoq_l()` and `strtouq_l() `are not provided.  These are extensions to
 128 deprecated functions - we should not be encouraging people to use deprecated
 129 interfaces.
 130
 131 Locale Placeholders
 132 -------------------
 133
 134 The pointer values 0 and -1 have special meanings as `locale_t` values.  Any
 135 public function that accepts a `locale_t` parameter must use the `FIX_LOCALE()`
 136 macro on it before using it.  For efficiency, this can be emitted in functions
 137 which *only* use their locale parameter as an argument to another public
 138 function, as the callee will do the `FIX_LOCALE()` itself.
 139
 140 Potential Improvements
 141 ----------------------
 142
 143 Currently, the current rune set is accessed via a function call.  This makes it
 144 fairly expensive to use any of the ctype.h functions.  We could improve this
 145 quite a lot by storing the rune locale data in a __thread-qualified variable.
 146
 147 Several of the existing FreeBSD locale-aware functions appear to be wrong.  For
 148 example, most of the `strto*()` family should probably use `digittoint_l()`,
 149 but instead they assume ASCII.  These will break if using a character encoding
 150 that does not put numbers and the letters A-F in the same location as ASCII.
 151 Some functions, like `strcoll()` only work on single-byte encodings.  No
 152 attempt has been made to fix existing limitations in the libc functions other
 153 than to add support for xlocale.
 154
 155 Intuitively, setting a thread-local locale should ensure that all locale-aware
 156 functions can be used safely from that thread.  In fact, this is not the case
 157 in either this implementation or the Darwin one.  You must call `duplocale()`
 158 or `newlocale()` before calling `uselocale()`.  This is a bit ugly, and it
 159 would be better if libc ensure that every thread had its own locale object.