From ed7ed4534ddb8125f00b2a8e022edd08bfc5606d Mon Sep 17 00:00:00 2001 From: Howard Hinnant Date: Sat, 30 Sep 2017 15:58:29 -0400 Subject: [PATCH] Document get_tzdb_list() --- d0355r4.html | 3 +- tz.html | 249 ++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 188 insertions(+), 64 deletions(-) diff --git a/d0355r4.html b/d0355r4.html index b3979c9..c5e32f8 100644 --- a/d0355r4.html +++ b/d0355r4.html @@ -37,7 +37,7 @@ Document number: D0355R4

Howard E. Hinnant
-2017-09-16
+2017-09-30

Extending <chrono> to Calendars and Time Zones

@@ -10088,6 +10088,7 @@ zoned_time<Duration, TimeZonePtr>::zoned_time(TimeZonePtr z, const zoned_t

Effects: Equivalent to construction with {z, y}.

+

Note: The choose parameter is allowed here, but has no impact.

diff --git a/tz.html b/tz.html index b0b69bb..45fb4ac 100644 --- a/tz.html +++ b/tz.html @@ -557,7 +557,7 @@ Full formatting and parsing facilities are available with time_put- formatting strings.

-

Examples

+

Examples

Flight time

@@ -1019,21 +1019,47 @@ functions access it. 
 struct tzdb
 {
-    std::string            version;
-    std::vector<time_zone> zones;
-    std::vector<link>      links;
-    std::vector<leap>      leaps;
-    std::vector<Rule>      rules;
+    string            version;
+    vector<time_zone> zones;
+    vector<link>      links;
+    vector<leap>      leaps;
+
+    const time_zone* locate_zone(string_view tz_name) const;
+    const time_zone* current_zone() const;
+};
+
+class tzdb_list
+{
+    std::atomic<tzdb*> head_{nullptr};  // exposition only
+
+public:
+    class const_iterator;
+
+    const tzdb& front() const noexcept;
+
+    const_iterator erase_after(const_iterator p) noexcept;
+
+    const_iterator begin() const noexcept;
+    const_iterator end()   const noexcept;
+
+    const_iterator cbegin() const noexcept;
+    const_iterator cend()   const noexcept;
 };

-The tzdb database is a singleton. And access to it is -read-only, except for reload_tzdb() which re-initializes it. -Each vector is sorted to enable fast lookup. You don't have to explicitly -program binary search lookups on it. That is handled by the API. But you can -explicitly iterate over and inspect this database. And knowing that it is sorted may -be of benefit to your inspection logic. +The tzdb_list database is a singleton. Access is +granted to it via the get_tzdb_list() function which +returns a reference to it. However this access is only needed for +those applications which need to have long uptimes and have a need to +update the time zone database while running. Other applications can +implicitly access the front() of this list via the +read-only namespace scope functions get_tzdb(), +locate_zone() and current_zone(). Each +vector in tzdb is sorted to enable fast +lookup. One can iterate over and inspect this database. And +multiple versions of the database can be used at once, via the +tzdb_list.

@@ -1063,18 +1089,52 @@ links and time zones. leaps will be missing on those platforms that do not ship with this information, which includes macOS and iOS.

-

  • -rules is missing. -

    • -const tzdb& get_tzdb();
+const time_zone* tzdb::locate_zone(string_view tz_name) const;

    -Effects: If this is the first access to the database, will initialize -the database. If tz.cpp was compiled with the configuration macro +Returns: If a time_zone is found for which +name() == tz_name, returns a pointer to that time_zone. +Otherwise if a link is found where tz_name == link.name(), +then a pointer is returned to the time_zone for which +zone.name() == link.target() [Note: A link is an +alternative name for a time_zone. — end note] +

    +

    +Throws: If a const time_zone* can not be found as +described in the Returns clause, throws a +runtime_error. [Note: On non-exceptional return, +the return value is always a pointer to a valid +time_zone. — end note] +

    +
    + +
    +const time_zone* tzdb::current_zone() const;
+
    +
    +

    +Returns: A const time_zone* referring to the time zone which your +computer has set as its local time zone. +

    +
    + +
    +list<tzdb>& get_tzdb_list();
+
    +
    +

    +Effects: If this is the first access to the database, will +initialize the database. If this call initializes the database, the +resulting database will be a tzdb_list which holds a +single initialized tzdb. +

    + +

    +If tz.cpp was compiled with the configuration macro AUTO_DOWNLOAD == 1, initialization will include checking the IANA website for the latest version, and downloading the latest version if your local version is out of @@ -1085,46 +1145,44 @@ decompress the IANA database from the IANA website and place it at the location referred to by the install configuration variable.

    +

    AUTO_DOWNLOAD == 1 requires linking tz.cpp to libcurl.

    +

    -Returns: A const reference to the database. +Returns: A reference to the database.

    Thread Safety: It is safe to call this function from multiple threads at -one time. There will be no race to initialize the singleton database as long as -your compiler implements threadsafe function-local statics as specified by C++11. +one time.

    -Throws: std::runtime_error if for any reason a reference can not -be returned to a valid tzdb. +Throws: runtime_error if for any reason a +reference can not be returned to a valid +list<tzdb>& containing one or more valid +tzdb. 

    -const time_zone* locate_zone(const std::string& tz_name);
+const tzdb& get_tzdb();

    -Effects: Calls get_tzdb() which will initialize the timezone -database if this is the first reference to the database. +Returns: get_tzdb_list().front().

    +
    + +
    +const time_zone* locate_zone(string_view tz_name);
+
    +

    -Returns: If a time_zone is found for which -name() == tz_name, returns a pointer to that time_zone. -Otherwise if a link is found where tz_name == link.name(), -then a pointer is returned to the time_zone for which -zone.name() == link.target() [Note: A link is an -alternative name for a time_zone. — end note] -

    -

    -Throws: Any exception propagated from get_tzdb(). If a -const time_zone* can not be found as described in the -Returns clause, throws a std::runtime_error. [Note: -On non-exceptional return, the return value is always a pointer to a -valid time_zone. — end note] +Returns: get_tzdb().locate_zone(tz_name) which +will initialize the timezone database if this is the first reference +to the database.

    @@ -1132,17 +1190,80 @@ valid time_zone. — end note] const time_zone* current_zone();
    -Effects: Calls locate_zone() which will initialize the timezone -database if this is the first reference to the database. +

    +Returns: get_tzdb().current_zone(). +

    +
    + +tzdb_list::const_iterator is a constant iterator which meets the +forward iterator requirements and has a value type of tzdb. + +
    +const tzdb& tzdb_list::front() const noexcept;
+
    +
    +

    +Returns: *head_.

    -Returns: A const time_zone* referring to the time zone which your -computer has set as its local time zone. +Remarks: this operation is thread safe with respect to reload_tzdb(). +[Note: reload_tzdb() pushes a new tzdb onto the front +of this container. — end note] +

    +
    + +
    +tzdb::const_iterator tzdb::erase_after(const_iterator p) noexcept;
+
    +
    +

    +Requires: The iterator following p is dereferenceable.

    -Throws: Any exception propagated from locate_zone(). -[Note: On non-exceptional return, the return value is always a -pointer to a valid time_zone. — end note] +Effects: Erases the tzdb referred to by the iterator following +p. +

    +

    +Returns: An iterator pointing to the element following the one that was erased, +or end() if no such element exists. +

    +

    +Remarks: No pointers, references or iterators are invalidated except those referring +to the erased tzdb. +

    +

    +Note: It is not possible to erase the tzdb referred to by +begin(). +

    +
    + +
    +tzdb::const_iterator tzdb::begin() const noexcept;
+
    +
    +Returns: An iterator referring to the first tzdb in the container. +
    + +
    +tzdb::const_iterator tzdb::end() const noexcept;
+
    +
    +Returns: An iterator referring to the position one past the +last tzdb in the container. +
    + +
    +tzdb::const_iterator tzdb::cbegin() const noexcept;
+
    +
    +Returns: begin(). +
    + +
    +tzdb::const_iterator tzdb::cend() const noexcept;
+
    +
    +Returns: end(). 
    @@ -1159,34 +1280,35 @@ If If tz.cpp was compiled with the configuration macro
 IANA website.  If the
 IANA website is unavailable, or if the
 latest version is already installed, there are no effects.  Otherwise, a new version
-is available.  It is downloaded and installed, and then the program re-initializes
-the tzdb singleton from the new disk files.
+is available.  It is downloaded and installed, and then the program initializes
+a new tzdb from the new disk files and pushes it to the front of the
+tzdb_list accessed by get_tzdb_list().
 
    
 
 
    
 If tz.cpp was compiled with the configuration macro
-AUTO_DOWNLOAD == 0, this function re-initializes the
-tzdb singleton from the disk files.  You can manually replace the
-database without ill-effects after your program has called
-get_tzdb() and before it calls reload_tzdb(), as there is
-no access to the files on disk between the first call to get_tzdb() and
-subsequent calls to reload_tzdb().
+AUTO_DOWNLOAD == 0, this function initializes a new
+tzdb from the disk files and pushes it to the front of the
+tzdb_list accessed by get_tzdb_list().
+You can manually replace the database without ill-effects after your
+program has called get_tzdb() and before it calls
+reload_tzdb(), as there is no access to the files on disk
+between the first call to get_tzdb() and subsequent calls
+to reload_tzdb().
 
    
 
 
    
-Returns: A const reference to the database.
+Returns: get_tzdb_list().front().
 
    
 
    
-Thread Safety:  This function is not thread safe.  You must
-provide your own synchronization among threads accessing the time zone database
-to safely use this function.  If this function re-initializes the database (as
-it always does when AUTO_DOWNLOAD == 0), all outstanding
-const time_zone* are invalidated (including those held within
-zoned_time objects).  And afterwards, all outstanding
-sys_info may hold obsolete data.
+Remarks: No pointers, references or iterators are invalidated.
 
    
 
    
-Throws: std::runtime_error if for any reason a reference can not
+Thread Safety:  This function is thread safe with respect to front()
+and erase_after().
+
    
+
    
+Throws: runtime_error if for any reason a reference can not
 be returned to a valid tzdb.
 
    
 
@@ -2138,6 +2260,7 @@ zoned_time<Duration, TimeZonePtr>::zoned_time(TimeZonePtr z, const zoned_t
 
    
 Effects: Equivalent to construction with {z, y}.
 
    
+
    
 Note: The choose parameter is allowed here, but has no impact.