libcxx/docs/DesignDocs/TimeZone.rst

   1 =================
   2 Time Zone Support
   3 =================
   4
   5 Introduction
   6 ============
   7
   8 Starting with C++20 the ``<chrono>`` library has support for time zones.
   9 These are available in the
  10 `IANA Time Zone Database <https://data.iana.org/time-zones/tz-link.html>`_.
  11 This page describes the design decisions and trade-offs made to implement this
  12 feature. This page contains several links with more information regarding the
  13 contents of the IANA database, this page assumes the reader is familiar with
  14 this information.
  15
  16 Which version of the Time Zone Database to use
  17 ==============================================
  18
  19 The data of the database is available on several platforms in different forms:
  20
  21 - Typically Unix systems ship the database as
  22   `TZif files <https://www.rfc-editor.org/rfc/rfc8536.html>`_. This format has
  23   3 versions and the ``time_zone_link`` information is not always available.
  24   If available, they are symlinks in the file system.
  25   These files don't provide the database version information. This information
  26   is needed for the functions ``std::chrono:: remote_version()`` and
  27   ``std::chrono::reload_tzdb()``.
  28
  29 - On several Unix systems the time zone source files are available. These files
  30   are stored in several regions, mainly the continents. This file contains a
  31   large amount of comment with historical information regarding time zones.
  32   The format is documented in the
  33   `IANA documentation <https://data.iana.org/time-zones/tz-how-to.html>`_
  34   and in the `man page <https://man7.org/linux/man-pages/man8/zic.8.html>`_ of zic.
  35   The disadvantage of this version is that at least Linux versions don't have
  36   the database version information. This information is needed for the functions
  37   ``std::chrono:: remote_version()`` and ``std::chrono::reload_tzdb()``.
  38
  39 - On Linux systems ``tzdata.zi`` is available. This contains the same
  40   information as the source files but in one file without the comments. This
  41   file uses the same format as the sources, but shortens the names. For example
  42   ``Rule`` is abbreviated to ``R``. This file contains the database version
  43   information.
  44
  45 The disadvantage of the ``TZif`` format (which is a binary format) is that it's
  46 not possible to get the proper ``time_zone_link`` information on all platforms.
  47 The time zone database version number is also missing from ``TZif`` files.
  48 Since the time zone database is supposed to contain both these informations,
  49 ``TZif`` files can't be used to create a conforming implementation.
  50
  51 Since it's easier to parse one file than a set of files we decided
  52 to use the ``tzdata.zi``. The other benefit is that the ``tzdata.zi`` file
  53 contains the database version information needed for a conforming
  54 implementation.
  55
  56 The ``tzdata.zi`` file is not available on all platforms as of August 2023, so
  57 some vendors will need to make changes to their platform. Most vendors already
  58 ship the database, so they only need to adjust the packaging of their time zone
  59 package to include the files we require. One notable exception is Windows,
  60 where no IANA time zone database is provided at all. However it's possible for
  61 Windows packagers to add these files to their libc++ packages. The IANA
  62 databases can be
  63 `downloaded <https://data.iana.org/time-zones/releases/>`_.
  64
  65 An alternative would be to ship the database with libc++, either as a file or
  66 compiled in the dylib. The text file is about 112 KB. For now libc++ will not
  67 ship this file. If it's hard to get vendors to ship these files we can
  68 reconsider based on that information.
  69
  70 Leap seconds
  71 ------------
  72
  73 For the leap seconds libc++ will use the source file ``leap-seconds.list``.
  74 This file is easier to parse than the ``leapseconds`` file. Both files are
  75 present on Linux, but not always on other platforms. Since these platforms need
  76 to change their packaging for ``tzdata.zi``, adding two instead of one files
  77 seems a small change.
  78
  79
  80 Updating the Time Zone Database
  81 ===============================
  82
  83 Per `[time.zone.db.remote]/1 <http://eel.is/c++draft/time.zone#db.remote-1>`_
  84
  85 .. code-block:: text
  86
  87   The local time zone database is that supplied by the implementation when the
  88   program first accesses the database, for example via current_zone(). While the
  89   program is running, the implementation may choose to update the time zone
  90   database. This update shall not impact the program in any way unless the
  91   program calls the functions in this subclause. This potentially updated time
  92   zone database is referred to as the remote time zone database.
  93
  94 There is an update mechanism in libc++, however this is not done automatically.
  95 Invoking the function ``std::chrono::remote_version()`` will parse the version
  96 information of the ``tzdata.zi`` file and return that information. Similarly,
  97 ``std::chrono::reload_tzdb()`` will parse the ``tzdata.zi`` and
  98 ``leap-seconds.list`` again. This makes it possible to update the database if
  99 needed by the application and gives the user full power over the update policy.
 100
 101 This approach has several advantages:
 102
 103 - It is simple to implement.
 104 - The library does not need to start a periodic background process to poll
 105   changes to the filesystem. When using a background process, it may become
 106   active when the application is busy with its core task, taking away resources
 107   from that task.
 108 - If there is no threading available this polling
 109   becomes more involved. For example, query the file every *x* calls to
 110   ``std::chrono::get_tzdb()``. This mean calls to ``std::chrono::get_tzdb()``
 111   would have different performance characteristics.
 112
 113 The small drawback is:
 114
 115 - On platforms with threading enabled updating the database may take longer.
 116   On these platforms the remote database could have been loaded in a background
 117   process.
 118
 119 Another issue with the automatic update is that it may not be considered
 120 Standard compliant, since the Standard uses the wording "This update shall not
 121 impact the program in any way". Using resources could be considered as
 122 impacting the program.