1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 * vim: set ts=8 sts=2 et sw=2 tw=80: 3 * This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 #ifndef vm_DateTime_h 8 #define vm_DateTime_h 9 10 #include "mozilla/Assertions.h" 11 #include "mozilla/UniquePtr.h" 12 13 #include <stdint.h> 14 15 #include "js/Utility.h" 16 #include "threading/ExclusiveData.h" 17 18 #if JS_HAS_INTL_API && !MOZ_SYSTEM_ICU 19 # include "unicode/uversion.h" 20 21 U_NAMESPACE_BEGIN 22 class TimeZone; 23 U_NAMESPACE_END 24 #endif /* JS_HAS_INTL_API && !MOZ_SYSTEM_ICU */ 25 26 namespace js { 27 28 /* Constants defined by ES5 15.9.1.10. */ 29 constexpr double HoursPerDay = 24; 30 constexpr double MinutesPerHour = 60; 31 constexpr double SecondsPerMinute = 60; 32 constexpr double msPerSecond = 1000; 33 constexpr double msPerMinute = msPerSecond * SecondsPerMinute; 34 constexpr double msPerHour = msPerMinute * MinutesPerHour; 35 36 /* ES5 15.9.1.2. */ 37 constexpr double msPerDay = msPerHour * HoursPerDay; 38 39 /* 40 * Additional quantities not mentioned in the spec. Be careful using these! 41 * They aren't doubles and aren't defined in terms of all the other constants. 42 * If you need constants that trigger floating point semantics, you'll have to 43 * manually cast to get it. 44 */ 45 constexpr unsigned SecondsPerHour = 60 * 60; 46 constexpr unsigned SecondsPerDay = SecondsPerHour * 24; 47 48 constexpr double StartOfTime = -8.64e15; 49 constexpr double EndOfTime = 8.64e15; 50 51 extern bool InitDateTimeState(); 52 53 extern void FinishDateTimeState(); 54 55 enum class ResetTimeZoneMode : bool { 56 DontResetIfOffsetUnchanged, 57 ResetEvenIfOffsetUnchanged, 58 }; 59 60 /** 61 * Engine-internal variant of JS::ResetTimeZone with an additional flag to 62 * control whether to forcibly reset all time zone data (this is the default 63 * behavior when calling JS::ResetTimeZone) or to try to reuse the previous 64 * time zone data. 65 */ 66 extern void ResetTimeZoneInternal(ResetTimeZoneMode mode); 67 68 /** 69 * ICU's default time zone, used for various date/time formatting operations 70 * that include the local time in the representation, is allowed to go stale 71 * for unfortunate performance reasons. Call this function when an up-to-date 72 * default time zone is required, to resync ICU's default time zone with 73 * reality. 74 */ 75 extern void ResyncICUDefaultTimeZone(); 76 77 /** 78 * Stores date/time information, particularly concerning the current local 79 * time zone, and implements a small cache for daylight saving time offset 80 * computation. 81 * 82 * The basic idea is premised upon this fact: the DST offset never changes more 83 * than once in any thirty-day period. If we know the offset at t_0 is o_0, 84 * the offset at [t_1, t_2] is also o_0, where t_1 + 3_0 days == t_2, 85 * t_1 <= t_0, and t0 <= t2. (In other words, t_0 is always somewhere within a 86 * thirty-day range where the DST offset is constant: DST changes never occur 87 * more than once in any thirty-day period.) Therefore, if we intelligently 88 * retain knowledge of the offset for a range of dates (which may vary over 89 * time), and if requests are usually for dates within that range, we can often 90 * provide a response without repeated offset calculation. 91 * 92 * Our caching strategy is as follows: on the first request at date t_0 compute 93 * the requested offset o_0. Save { start: t_0, end: t_0, offset: o_0 } as the 94 * cache's state. Subsequent requests within that range are straightforwardly 95 * handled. If a request for t_i is far outside the range (more than thirty 96 * days), compute o_i = dstOffset(t_i) and save { start: t_i, end: t_i, 97 * offset: t_i }. Otherwise attempt to *overextend* the range to either 98 * [start - 30d, end] or [start, end + 30d] as appropriate to encompass 99 * t_i. If the offset o_i30 is the same as the cached offset, extend the 100 * range. Otherwise the over-guess crossed a DST change -- compute 101 * o_i = dstOffset(t_i) and either extend the original range (if o_i == offset) 102 * or start a new one beneath/above the current one with o_i30 as the offset. 103 * 104 * This cache strategy results in 0 to 2 DST offset computations. The naive 105 * always-compute strategy is 1 computation, and since cache maintenance is a 106 * handful of integer arithmetic instructions the speed difference between 107 * always-1 and 1-with-cache is negligible. Caching loses if two computations 108 * happen: when the date is within 30 days of the cached range and when that 109 * 30-day range crosses a DST change. This is relatively uncommon. Further, 110 * instances of such are often dominated by in-range hits, so caching is an 111 * overall slight win. 112 * 113 * Why 30 days? For correctness the duration must be smaller than any possible 114 * duration between DST changes. Past that, note that 1) a large duration 115 * increases the likelihood of crossing a DST change while reducing the number 116 * of cache misses, and 2) a small duration decreases the size of the cached 117 * range while producing more misses. Using a month as the interval change is 118 * a balance between these two that tries to optimize for the calendar month at 119 * a time that a site might display. (One could imagine an adaptive duration 120 * that accommodates near-DST-change dates better; we don't believe the 121 * potential win from better caching offsets the loss from extra complexity.) 122 */ 123 class DateTimeInfo { 124 static ExclusiveData<DateTimeInfo>* instance; 125 friend class ExclusiveData<DateTimeInfo>; 126 127 friend bool InitDateTimeState(); 128 friend void FinishDateTimeState(); 129 130 DateTimeInfo(); 131 ~DateTimeInfo(); 132 acquireLockWithValidTimeZone()133 static auto acquireLockWithValidTimeZone() { 134 auto guard = instance->lock(); 135 if (guard->timeZoneStatus_ != TimeZoneStatus::Valid) { 136 guard->updateTimeZone(); 137 } 138 return guard; 139 } 140 141 public: 142 // The spec implicitly assumes DST and time zone adjustment information 143 // never change in the course of a function -- sometimes even across 144 // reentrancy. So make critical sections as narrow as possible. 145 146 /** 147 * Get the DST offset in milliseconds at a UTC time. This is usually 148 * either 0 or |msPerSecond * SecondsPerHour|, but at least one exotic time 149 * zone (Lord Howe Island, Australia) has a fractional-hour offset, just to 150 * keep things interesting. 151 */ getDSTOffsetMilliseconds(int64_t utcMilliseconds)152 static int32_t getDSTOffsetMilliseconds(int64_t utcMilliseconds) { 153 auto guard = acquireLockWithValidTimeZone(); 154 return guard->internalGetDSTOffsetMilliseconds(utcMilliseconds); 155 } 156 157 /** 158 * The offset in seconds from the current UTC time to the current local 159 * standard time (i.e. not including any offset due to DST) as computed by the 160 * operating system. 161 */ utcToLocalStandardOffsetSeconds()162 static int32_t utcToLocalStandardOffsetSeconds() { 163 auto guard = acquireLockWithValidTimeZone(); 164 return guard->utcToLocalStandardOffsetSeconds_; 165 } 166 167 #if JS_HAS_INTL_API && !MOZ_SYSTEM_ICU 168 enum class TimeZoneOffset { UTC, Local }; 169 170 /** 171 * Return the time zone offset, including DST, in milliseconds at the 172 * given time. The input time can be either at UTC or at local time. 173 */ getOffsetMilliseconds(int64_t milliseconds,TimeZoneOffset offset)174 static int32_t getOffsetMilliseconds(int64_t milliseconds, 175 TimeZoneOffset offset) { 176 auto guard = acquireLockWithValidTimeZone(); 177 return guard->internalGetOffsetMilliseconds(milliseconds, offset); 178 } 179 180 /** 181 * Copy the display name for the current time zone at the given time, 182 * localized for the specified locale, into the supplied buffer. If the 183 * buffer is too small, an empty string is stored. The stored display name 184 * is null-terminated in any case. 185 */ timeZoneDisplayName(char16_t * buf,size_t buflen,int64_t utcMilliseconds,const char * locale)186 static bool timeZoneDisplayName(char16_t* buf, size_t buflen, 187 int64_t utcMilliseconds, const char* locale) { 188 auto guard = acquireLockWithValidTimeZone(); 189 return guard->internalTimeZoneDisplayName(buf, buflen, utcMilliseconds, 190 locale); 191 } 192 #else 193 /** 194 * Return the local time zone adjustment (ES2019 20.3.1.7) as computed by 195 * the operating system. 196 */ localTZA()197 static int32_t localTZA() { 198 return utcToLocalStandardOffsetSeconds() * msPerSecond; 199 } 200 #endif /* JS_HAS_INTL_API && !MOZ_SYSTEM_ICU */ 201 202 private: 203 // The two methods below should only be called via js::ResetTimeZoneInternal() 204 // and js::ResyncICUDefaultTimeZone(). 205 friend void js::ResetTimeZoneInternal(ResetTimeZoneMode); 206 friend void js::ResyncICUDefaultTimeZone(); 207 resetTimeZone(ResetTimeZoneMode mode)208 static void resetTimeZone(ResetTimeZoneMode mode) { 209 auto guard = instance->lock(); 210 guard->internalResetTimeZone(mode); 211 } 212 resyncICUDefaultTimeZone()213 static void resyncICUDefaultTimeZone() { 214 auto guard = acquireLockWithValidTimeZone(); 215 (void)guard; 216 } 217 218 struct RangeCache { 219 // Start and end offsets in seconds describing the current and the 220 // last cached range. 221 int64_t startSeconds, endSeconds; 222 int64_t oldStartSeconds, oldEndSeconds; 223 224 // The current and the last cached offset in milliseconds. 225 int32_t offsetMilliseconds; 226 int32_t oldOffsetMilliseconds; 227 228 void reset(); 229 230 void sanityCheck(); 231 }; 232 233 enum class TimeZoneStatus : uint8_t { Valid, NeedsUpdate, UpdateIfChanged }; 234 235 TimeZoneStatus timeZoneStatus_; 236 237 /** 238 * The offset in seconds from the current UTC time to the current local 239 * standard time (i.e. not including any offset due to DST) as computed by the 240 * operating system. 241 * 242 * Cached because retrieving this dynamically is Slow, and a certain venerable 243 * benchmark which shall not be named depends on it being fast. 244 * 245 * SpiderMonkey occasionally and arbitrarily updates this value from the 246 * system time zone to attempt to keep this reasonably up-to-date. If 247 * temporary inaccuracy can't be tolerated, JSAPI clients may call 248 * JS::ResetTimeZone to forcibly sync this with the system time zone. 249 * 250 * In most cases this value is consistent with the raw time zone offset as 251 * returned by the ICU default time zone (`icu::TimeZone::getRawOffset()`), 252 * but it is possible to create cases where the operating system default time 253 * zone differs from the ICU default time zone. For example ICU doesn't 254 * support the full range of TZ environment variable settings, which can 255 * result in <ctime> returning a different time zone than what's returned by 256 * ICU. One example is "TZ=WGT3WGST,M3.5.0/-2,M10.5.0/-1", where <ctime> 257 * returns -3 hours as the local offset, but ICU flat out rejects the TZ value 258 * and instead infers the default time zone via "/etc/localtime" (on Unix). 259 * This offset can also differ from ICU when the operating system and ICU use 260 * different tzdata versions and the time zone rules of the current system 261 * time zone have changed. Or, on Windows, when the Windows default time zone 262 * can't be mapped to a IANA time zone, see for example 263 * <https://unicode-org.atlassian.net/browse/ICU-13845>. 264 * 265 * When ICU is exclusively used for time zone computations, that means when 266 * |JS_HAS_INTL_API && !MOZ_SYSTEM_ICU| is true, this field is only used to 267 * detect system default time zone changes. It must not be used to convert 268 * between local and UTC time, because, as outlined above, this could lead to 269 * different results when compared to ICU. 270 */ 271 int32_t utcToLocalStandardOffsetSeconds_; 272 273 RangeCache dstRange_; // UTC-based ranges 274 275 #if JS_HAS_INTL_API && !MOZ_SYSTEM_ICU 276 // ICU's TimeZone class is currently only available through the C++ API, 277 // see <https://unicode-org.atlassian.net/browse/ICU-13706>. Due to the 278 // lack of a stable ABI in C++, we therefore need to restrict this class 279 // to only use ICU when we use our in-tree ICU copy. 280 281 // Use the full date-time range when we can use ICU's TimeZone support. 282 static constexpr int64_t MinTimeT = 283 static_cast<int64_t>(StartOfTime / msPerSecond); 284 static constexpr int64_t MaxTimeT = 285 static_cast<int64_t>(EndOfTime / msPerSecond); 286 287 RangeCache utcRange_; // localtime-based ranges 288 RangeCache localRange_; // UTC-based ranges 289 290 /** 291 * The current ICU time zone. Lazily constructed to avoid potential I/O 292 * access when initializing this class. 293 */ 294 mozilla::UniquePtr<icu::TimeZone> timeZone_; 295 296 /** 297 * Cached names of the standard and daylight savings display names of the 298 * current time zone for the default locale. 299 */ 300 JS::UniqueChars locale_; 301 JS::UniqueTwoByteChars standardName_; 302 JS::UniqueTwoByteChars daylightSavingsName_; 303 #else 304 // Restrict the data-time range to the minimum required time_t range as 305 // specified in POSIX. Most operating systems support 64-bit time_t 306 // values, but we currently still have some configurations which use 307 // 32-bit time_t, e.g. the ARM simulator on 32-bit Linux (bug 1406993). 308 // Bug 1406992 explores to use 64-bit time_t when supported by the 309 // underlying operating system. 310 static constexpr int64_t MinTimeT = 0; /* time_t 01/01/1970 */ 311 static constexpr int64_t MaxTimeT = 2145830400; /* time_t 12/31/2037 */ 312 #endif /* JS_HAS_INTL_API && !MOZ_SYSTEM_ICU */ 313 314 static constexpr int64_t RangeExpansionAmount = 30 * SecondsPerDay; 315 316 void internalResetTimeZone(ResetTimeZoneMode mode); 317 318 void updateTimeZone(); 319 320 void internalResyncICUDefaultTimeZone(); 321 322 int64_t toClampedSeconds(int64_t milliseconds); 323 324 using ComputeFn = int32_t (DateTimeInfo::*)(int64_t); 325 326 /** 327 * Get or compute an offset value for the requested seconds value. 328 */ 329 int32_t getOrComputeValue(RangeCache& range, int64_t seconds, 330 ComputeFn compute); 331 332 /** 333 * Compute the DST offset at the given UTC time in seconds from the epoch. 334 * (getDSTOffsetMilliseconds attempts to return a cached value from the 335 * dstRange_ member, but in case of a cache miss it calls this method.) 336 */ 337 int32_t computeDSTOffsetMilliseconds(int64_t utcSeconds); 338 339 int32_t internalGetDSTOffsetMilliseconds(int64_t utcMilliseconds); 340 341 #if JS_HAS_INTL_API && !MOZ_SYSTEM_ICU 342 /** 343 * Compute the UTC offset in milliseconds for the given local time. Called 344 * by internalGetOffsetMilliseconds on a cache miss. 345 */ 346 int32_t computeUTCOffsetMilliseconds(int64_t localSeconds); 347 348 /** 349 * Compute the local time offset in milliseconds for the given UTC time. 350 * Called by internalGetOffsetMilliseconds on a cache miss. 351 */ 352 int32_t computeLocalOffsetMilliseconds(int64_t utcSeconds); 353 354 int32_t internalGetOffsetMilliseconds(int64_t milliseconds, 355 TimeZoneOffset offset); 356 357 bool internalTimeZoneDisplayName(char16_t* buf, size_t buflen, 358 int64_t utcMilliseconds, const char* locale); 359 360 icu::TimeZone* timeZone(); 361 #endif /* JS_HAS_INTL_API && !MOZ_SYSTEM_ICU */ 362 }; 363 364 } /* namespace js */ 365 366 #endif /* vm_DateTime_h */ 367