From ac62197c36c666a02dd342f73cacd9b4156afc7e Mon Sep 17 00:00:00 2001 From: Jonathan M Davis Date: Sun, 7 May 2017 00:51:00 +0200 Subject: [PATCH 1/4] Add the MonoTime equivalents of std.datetime.StopWatch/benchmark. std.datetime.package has StopWatch, benchmark, comparingBenchmark, and measureTime, all of which use TickDuration (which would be deprecated, but it can't be deprecated as long as those functions in std.datetime are deprecated). This commit introduces std.datetime.stopwatch to replace those functions in std.datetime. In order to avoid symbol conflicts, std.datetime.stopwatch will not be publicly import in std.datetime.package until the old symbols have been removed. std.datetime.experimental.stopwatch contains StopWatch and benchmark which have essentially the same APIs as the ones in std.datetime.package, but they use MonoTime and Duration. comparingBenchmark has not been ported to MonoTime and Duration, because it is simply a wrapper around benchmark. measureTime has not been ported to MonoTime and Duration, because it is equivalent to using StopWatch with a scope(exit) statement. The old functionality will be deprecated the major release after the new symbols have been introduced. --- posix.mak | 4 +- std/datetime/stopwatch.d | 425 +++++++++++++++++++++++++++++++++++++++ win32.mak | 6 + win64.mak | 5 + 4 files changed, 438 insertions(+), 2 deletions(-) create mode 100644 std/datetime/stopwatch.d diff --git a/posix.mak b/posix.mak index 81c5c2856ba..0cb66aadefa 100644 --- a/posix.mak +++ b/posix.mak @@ -181,7 +181,7 @@ PACKAGE_std_experimental = checkedint typecons PACKAGE_std_algorithm = comparison iteration mutation package searching setops \ sorting PACKAGE_std_container = array binaryheap dlist package rbtree slist util -PACKAGE_std_datetime = date interval package systime timezone +PACKAGE_std_datetime = date interval package stopwatch systime timezone PACKAGE_std_digest = crc digest hmac md murmurhash ripemd sha PACKAGE_std_experimental_logger = core filelogger \ nulllogger multilogger package @@ -558,7 +558,7 @@ publictests: $(LIB) has_public_example: $(LIB) # checks whether public function have public examples (for now some modules are excluded) rm -rf ./out - DFLAGS="$(DFLAGS) $(LIB) -defaultlib= -debuglib= $(LINKDL)" $(DUB) --compiler=$${PWD}/$(DMD) --root=../tools/styles -c has_public_example -- --inputdir . --ignore "etc,array.d,allocator,base64.d,bitmanip.d,concurrency.d,conv.d,csv.d,datetime/date.d,datetime/interval.d,datetime/package.d,datetime/systime.d,datetime/timezone.d,demangle.d,digest/hmac.d,digest/sha.d,encoding.d,exception.d,file.d,format.d,getopt.d,index.d,internal,isemail.d,json.d,logger/core.d,logger/nulllogger.d,math.d,mathspecial.d,net/curl.d,numeric.d,parallelism.d,path.d,process.d,random.d,range,regex/package.d,socket.d,stdio.d,string.d,traits.d,typecons.d,uni.d,unittest.d,uri.d,utf.d,uuid.d,xml.d,zlib.d" + DFLAGS="$(DFLAGS) $(LIB) -defaultlib= -debuglib= $(LINKDL)" $(DUB) --compiler=$${PWD}/$(DMD) --root=../tools/styles -c has_public_example -- --inputdir . --ignore "etc,array.d,allocator,base64.d,bitmanip.d,concurrency.d,conv.d,csv.d,datetime/date.d,datetime/interval.d,datetime/package.d,datetime/stopwatch.d,datetime/systime.d,datetime/timezone.d,demangle.d,digest/hmac.d,digest/sha.d,encoding.d,exception.d,file.d,format.d,getopt.d,index.d,internal,isemail.d,json.d,logger/core.d,logger/nulllogger.d,math.d,mathspecial.d,net/curl.d,numeric.d,parallelism.d,path.d,process.d,random.d,range,regex/package.d,socket.d,stdio.d,string.d,traits.d,typecons.d,uni.d,unittest.d,uri.d,utf.d,uuid.d,xml.d,zlib.d" .PHONY : auto-tester-build auto-tester-build: all checkwhitespace diff --git a/std/datetime/stopwatch.d b/std/datetime/stopwatch.d new file mode 100644 index 00000000000..69ab822921d --- /dev/null +++ b/std/datetime/stopwatch.d @@ -0,0 +1,425 @@ +// Written in the D programming language + +/++ + Module containing some basic benchmarking and timing functionality. + + For convenience, this module publicly imports $(MREF core,time). + + $(RED Unlike the other modules in std.datetime, this module is not currently + publicly imported in std.datetime.package, because the old + versions of this functionality which use + $(REF TickDuration,core,time) are in std.datetime.package and would + conflict with the symbols in this module. After the old symbols have + gone through the deprecation cycle and have been removed, then this + module will be publicly imported in std.datetime.package.) + + License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0). + Authors: Jonathan M Davis and Kato Shoichi + Source: $(PHOBOSSRC std/datetime/_stopwatch.d) ++/ +module std.datetime.stopwatch; + +public import core.time; +import std.typecons : Flag; + +/++ + Used by StopWatch to indicate whether it should start immediately upon + construction. + + If set to $(D AutoStart.no), then the StopWatch is not started when it is + constructed. + + Otherwise, if set to $(D AutoStart.yes), then the StopWatch is started when + it is constructed. + +/ +alias AutoStart = Flag!"autoStart"; + + +/++ + StopWatch is used to measure time just like one would do with a physical + stopwatch, including stopping, restarting, and/or resetting it. + + $(REF MonoTime,core,time) is used to hold the time, and it uses the system's + monotonic clock, which is high precision and never counts backwards (unlike + the wall clock time, which $(I can) count backwards, which is why + $(REF SysTime,std,datetime,systime) should not be used for timing). + + Note that the precision of StopWatch differs from system to system. It is + impossible for it to be the same for all systems, since the precision of the + system clock and other system-dependent and situation-dependent factors + (such as the overhead of a context switch between threads) varies from system + to system and can affect StopWatch's accuracy. + +/ +struct StopWatch +{ +public: + + /// + @system nothrow @nogc unittest + { + import core.thread : Thread; + + auto sw = StopWatch(AutoStart.yes); + + Duration t1 = sw.peek(); + Thread.sleep(usecs(1)); + Duration t2 = sw.peek(); + assert(t2 > t1); + + Thread.sleep(usecs(1)); + sw.stop(); + + Duration t3 = sw.peek(); + assert(t3 > t2); + Duration t4 = sw.peek(); + assert(t3 == t4); + + sw.start(); + Thread.sleep(usecs(1)); + + Duration t5 = sw.peek(); + assert(t5 > t4); + + // If stopping or resetting the StopWatch is not required, then + // MonoTime can easily be used by itself without StopWatch. + auto before = MonoTime.currTime; + // do stuff... + auto timeElapsed = MonoTime.currTime - before; + } + + /++ + Constructs a StopWatch. Whether it starts immediately depends on the + $(LREF AutoStart) argument. + + If $(D StopWatch.init) is used, then the constructed StopWatch isn't + running (and can't be, since no constructor ran). + +/ + this(AutoStart autostart) @safe nothrow @nogc + { + if (autostart) + start(); + } + + /// + @system nothrow @nogc unittest + { + import core.thread : Thread; + + { + auto sw = StopWatch(AutoStart.yes); + assert(sw.running); + Thread.sleep(usecs(1)); + assert(sw.peek() > Duration.zero); + } + { + auto sw = StopWatch(AutoStart.no); + assert(!sw.running); + Thread.sleep(usecs(1)); + assert(sw.peek() == Duration.zero); + } + { + StopWatch sw; + assert(!sw.running); + Thread.sleep(usecs(1)); + assert(sw.peek() == Duration.zero); + } + + assert(StopWatch.init == StopWatch(AutoStart.no)); + assert(StopWatch.init != StopWatch(AutoStart.yes)); + } + + + /++ + Resets the StopWatch. + + The StopWatch can be reset while it's running, and resetting it while + it's running will not cause it to stop. + +/ + void reset() @safe nothrow @nogc + { + if (_running) + _timeStarted = MonoTime.currTime; + _ticksElapsed = 0; + } + + /// + @system nothrow @nogc unittest + { + import core.thread : Thread; + + auto sw = StopWatch(AutoStart.yes); + Thread.sleep(usecs(1)); + sw.stop(); + assert(sw.peek() > Duration.zero); + sw.reset(); + assert(sw.peek() == Duration.zero); + } + + @system nothrow @nogc unittest + { + import core.thread : Thread; + + auto sw = StopWatch(AutoStart.yes); + Thread.sleep(msecs(1)); + assert(sw.peek() > msecs(1)); + immutable before = MonoTime.currTime; + + // Just in case the system clock is slow enough or the system is fast + // enough for the call to MonoTime.currTime inside of reset to get + // the same that we just got by calling MonoTime.currTime. + Thread.sleep(usecs(1)); + + sw.reset(); + assert(sw.peek() < msecs(1)); + assert(sw._timeStarted > before); + assert(sw._timeStarted < MonoTime.currTime); + } + + + /++ + Starts the StopWatch. + + start should not be called if the StopWatch is already running. + +/ + void start() @safe nothrow @nogc + in { assert(!_running, "start was called when the StopWatch was already running."); } + body + { + _running = true; + _timeStarted = MonoTime.currTime; + } + + /// + @system nothrow @nogc unittest + { + import core.thread : Thread; + + StopWatch sw; + assert(!sw.running); + assert(sw.peek() == Duration.zero); + sw.start(); + assert(sw.running); + Thread.sleep(usecs(1)); + assert(sw.peek() > Duration.zero); + } + + + /++ + Stops the StopWatch. + + stop should not be called if the StopWatch is not running. + +/ + void stop() @safe nothrow @nogc + in { assert(_running, "stop was called when the StopWatch was not running."); } + body + { + _running = false; + _ticksElapsed += MonoTime.currTime.ticks - _timeStarted.ticks; + } + + /// + @system nothrow @nogc unittest + { + import core.thread : Thread; + + auto sw = StopWatch(AutoStart.yes); + assert(sw.running); + Thread.sleep(usecs(1)); + immutable t1 = sw.peek(); + assert(t1 > Duration.zero); + + sw.stop(); + assert(!sw.running); + immutable t2 = sw.peek(); + assert(t2 > t1); + immutable t3 = sw.peek(); + assert(t2 == t3); + } + + + /++ + Peek at the amount of time that the the StopWatch has been running. + + This does not include any time during which the StopWatch was stopped but + does include $(I all) of the time that it was running and not just the + time since it was started last. + + Calling $(LREF reset) will reset this to $(D Duration.zero). + +/ + Duration peek() @safe const nothrow @nogc + { + enum hnsecsPerSecond = convert!("seconds", "hnsecs")(1); + immutable hnsecsMeasured = convClockFreq(_ticksElapsed, MonoTime.ticksPerSecond, hnsecsPerSecond); + return _running ? MonoTime.currTime - _timeStarted + hnsecs(hnsecsMeasured) + : hnsecs(hnsecsMeasured); + } + + /// + @system nothrow @nogc unittest + { + import core.thread : Thread; + + auto sw = StopWatch(AutoStart.no); + assert(sw.peek() == Duration.zero); + sw.start(); + + Thread.sleep(usecs(1)); + assert(sw.peek() >= usecs(1)); + + Thread.sleep(usecs(1)); + assert(sw.peek() >= usecs(2)); + + sw.stop(); + immutable stopped = sw.peek(); + Thread.sleep(usecs(1)); + assert(sw.peek() == stopped); + + sw.start(); + Thread.sleep(usecs(1)); + assert(sw.peek() > stopped); + } + + @safe nothrow @nogc unittest + { + assert(StopWatch.init.peek() == Duration.zero); + } + + + /++ + Sets the total time which the StopWatch has been running (i.e. what peek + returns). + + The StopWatch does not have to be stopped for setTimeElapsed to be + called, nor will calling it cause the StopWatch to stop. + +/ + void setTimeElapsed(Duration timeElapsed) @safe nothrow @nogc + { + enum hnsecsPerSecond = convert!("seconds", "hnsecs")(1); + _ticksElapsed = convClockFreq(timeElapsed.total!"hnsecs", hnsecsPerSecond, MonoTime.ticksPerSecond); + _timeStarted = MonoTime.currTime; + } + + /// + @system nothrow @nogc unittest + { + import core.thread : Thread; + + StopWatch sw; + sw.setTimeElapsed(hours(1)); + + // As discussed in MonoTime's documentation, converting between + // Duration and ticks is not exact, though it will be close. + // How exact it is depends on the frequency/resolution of the + // system's monotonic clock. + assert(abs(sw.peek() - hours(1)) < usecs(1)); + + sw.start(); + Thread.sleep(usecs(1)); + assert(sw.peek() > hours(1) + usecs(1)); + } + + + /++ + Returns whether this StopWatch is currently running. + +/ + @property bool running() @safe const pure nothrow @nogc + { + return _running; + } + + /// + @safe nothrow @nogc unittest + { + StopWatch sw; + assert(!sw.running); + sw.start(); + assert(sw.running); + sw.stop(); + assert(!sw.running); + } + + +private: + + // We track the ticks for the elapsed time rather than a Duration so that we + // don't lose any precision. + + bool _running = false; // Whether the StopWatch is currently running + MonoTime _timeStarted; // The time the StopWatch started measuring (i.e. when it was started or reset). + long _ticksElapsed; // Total time that the StopWatch ran before it was stopped last. +} + + +/++ + Benchmarks code for speed assessment and comparison. + + Params: + fun = aliases of callable objects (e.g. function names). Each callable + object should take no arguments. + n = The number of times each function is to be executed. + + Returns: + The amount of time (as a $(REF Duration,core,time)) that it took to call + each function $(D n) times. The first value is the length of time that + it took to call $(D fun[0]) $(D n) times. The second value is the length + of time it took to call $(D fun[1]) $(D n) times. Etc. + +/ +Duration[fun.length] benchmark(fun...)(uint n) +{ + Duration[fun.length] result; + auto sw = StopWatch(AutoStart.yes); + + foreach (i, unused; fun) + { + sw.reset(); + foreach (_; 0 .. n) + fun[i](); + result[i] = sw.peek(); + } + + return result; +} + +/// +@safe unittest +{ + import std.conv : to; + + int a; + void f0() {} + void f1() { auto b = a; } + void f2() { auto b = to!string(a); } + auto r = benchmark!(f0, f1, f2)(10_000); + Duration f0Result = r[0]; // time f0 took to run 10,000 times + Duration f1Result = r[1]; // time f1 took to run 10,000 times + Duration f2Result = r[2]; // time f2 took to run 10,000 times +} + +@safe nothrow unittest +{ + import std.conv : to; + + int a; + void f0() nothrow {} + void f1() nothrow { auto b = to!string(a); } + auto r = benchmark!(f0, f1)(1000); + assert(r[0] > Duration.zero); + assert(r[1] > Duration.zero); + assert(r[1] > r[0]); + assert(r[0] < seconds(1)); + assert(r[1] < seconds(1)); +} + +@safe nothrow @nogc unittest +{ + int f0Count; + int f1Count; + int f2Count; + void f0() nothrow @nogc { ++f0Count; } + void f1() nothrow @nogc { ++f1Count; } + void f2() nothrow @nogc { ++f2Count; } + auto r = benchmark!(f0, f1, f2)(552); + assert(f0Count == 552); + assert(f1Count == 552); + assert(f2Count == 552); +} diff --git a/win32.mak b/win32.mak index 896ec954066..3a9f3b48d37 100644 --- a/win32.mak +++ b/win32.mak @@ -199,6 +199,7 @@ SRC_STD_DATETIME= \ std\datetime\date.d \ std\datetime\interval.d \ std\datetime\package.d \ + std\datetime\stopwatch.d \ std\datetime\systime.d \ std\datetime\timezone.d @@ -454,6 +455,7 @@ DOCS= \ $(DOC)\std_datetime.html \ $(DOC)\std_datetime_date.html \ $(DOC)\std_datetime_interval.html \ + $(DOC)\std_datetime_stopwatch.html \ $(DOC)\std_datetime_systime.html \ $(DOC)\std_datetime_timezone.html \ $(DOC)\std_demangle.html \ @@ -639,6 +641,7 @@ cov : $(SRC_TO_COMPILE) $(LIB) $(DMD) -conf= -cov=95 -unittest -main -run std\datetime\date.d $(DMD) -conf= -cov=95 -unittest -main -run std\datetime\interval.d $(DMD) -conf= -cov=95 -unittest -main -run std\datetime\package.d + $(DMD) -conf= -cov=95 -unittest -main -run std\datetime\stopwatch.d $(DMD) -conf= -cov=95 -unittest -main -run std\datetime\systime.d $(DMD) -conf= -cov=95 -unittest -main -run std\datetime\timezone.d $(DMD) -conf= -cov=96 -unittest -main -run std\uuid.d @@ -844,6 +847,9 @@ $(DOC)\std_datetime_date.html : $(STDDOC) std\datetime\date.d $(DOC)\std_datetime_interval.html : $(STDDOC) std\datetime\interval.d $(DMD) -c -o- $(DDOCFLAGS) -Df$(DOC)\std_datetime_interval.html $(STDDOC) std\datetime\interval.d +$(DOC)\std_datetime_stopwatch.html : $(STDDOC) std\datetime\stopwatch.d + $(DMD) -c -o- $(DDOCFLAGS) -Df$(DOC)\std_datetime_stopwatch.html $(STDDOC) std\datetime\stopwatch.d + $(DOC)\std_datetime_systime.html : $(STDDOC) std\datetime\systime.d $(DMD) -c -o- $(DDOCFLAGS) -Df$(DOC)\std_datetime_systime.html $(STDDOC) std\datetime\systime.d diff --git a/win64.mak b/win64.mak index 292a6ddce5b..80bc8467ea0 100644 --- a/win64.mak +++ b/win64.mak @@ -224,6 +224,7 @@ SRC_STD_DATETIME= \ std\datetime\date.d \ std\datetime\interval.d \ std\datetime\package.d \ + std\datetime\stopwatch.d \ std\datetime\systime.d \ std\datetime\timezone.d @@ -479,6 +480,7 @@ DOCS= \ $(DOC)\std_datetime.html \ $(DOC)\std_datetime_date.html \ $(DOC)\std_datetime_interval.html \ + $(DOC)\std_datetime_stopwatch.html \ $(DOC)\std_datetime_systime.html \ $(DOC)\std_datetime_timezone.html \ $(DOC)\std_demangle.html \ @@ -820,6 +822,9 @@ $(DOC)\std_datetime_date.html : $(STDDOC) std\datetime\date.d $(DOC)\std_datetime_interval.html : $(STDDOC) std\datetime\interval.d $(DMD) -c -o- $(DDOCFLAGS) -Df$(DOC)\std_datetime_interval.html $(STDDOC) std\datetime\interval.d +$(DOC)\std_datetime_stopwatch.html : $(STDDOC) std\datetime\stopwatch.d + $(DMD) -c -o- $(DDOCFLAGS) -Df$(DOC)\std_datetime_stopwatch.html $(STDDOC) std\datetime\stopwatch.d + $(DOC)\std_datetime_systime.html : $(STDDOC) std\datetime\systime.d $(DMD) -c -o- $(DDOCFLAGS) -Df$(DOC)\std_datetime_systime.html $(STDDOC) std\datetime\systime.d From 55dffcfa95915849ed4a68bd2121cbfb726cf42f Mon Sep 17 00:00:00 2001 From: Jonathan M Davis Date: Sun, 7 May 2017 01:13:26 +0200 Subject: [PATCH 2/4] Update the changelog entry for splitting std.datetime. Now, it includes information on std.datetime.stopwatch. --- changelog/split-std-datetime.dd | 34 +++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/changelog/split-std-datetime.dd b/changelog/split-std-datetime.dd index 67c42db0a98..5e6f9b67578 100644 --- a/changelog/split-std-datetime.dd +++ b/changelog/split-std-datetime.dd @@ -5,6 +5,7 @@ std.datetime is now a package containing the following modules: $(UL $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_date.html, std.datetime.date)) $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_interval.html, std.datetime.interval)) + $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_stopwatch.html, std.datetime.stopwatch)) $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_systime.html, std.datetime.systime)) $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_timezone.html, std.datetime.timezone)) ) @@ -31,9 +32,30 @@ contains the time zone types. $(LINK2 $(PHOBOS_PATH)std_datetime.html, std.datetime.package) contains StopWatch and the benchmarking functions (so, they can only be imported via -std.datetime and not via a submodule). As those functions use TickDuration, -they are slated for deprecation and will be replaced with corresponding -functions that use MonoTime and Duration. Eventually, the new functions will -end up in a submodule of std.datetime, and the old ones will have been removed, -leaving nothing in std.datetime.package except for documentation and the public -imports of the rest of std.datetime. +std.datetime and not via a submodule). As those functions use +$(REF TickDuration,core,time) (which is being replaced by +$(REF MonoTime,core,time), they are slated for deprecation. + +$(LINK2 $(PHOBOS_PATH)std_datetime_stopwatch.html, std.datetime.stopwatch) has +been added. It contains versions of StopWatch and benchmark which have almost +the same API as the existing symbols, but they use $(REF MonoTime,core,time) and +$(REF Duration,core,time) instead of $(REF TickDuration,core,time). In the next +major release, the old functions in std.datetime.package will be deprecated, so +code which uses the old benchmarking functions should be updated to use +std.datetime.stopwatch. + +However, note that in order to avoid irreconcilable symbol conflicts between +the new and old versions, std.datetime.stopwatch will not be publicly imported +by std.datetime.package until the old symbols have been removed. So, for the +time being, code using $(REF StopWatch,std,datetime,stopwatch) or +$(REF StopWatch,std,datetime,benchmark) will need to import +std.datetime.stopwatch directly. Code which imports both std.datetime and +std.datetime.stopwatch will need to either use selective imports or fully +qualified symbols to reconcile the symbol conflicts, but no code will be +affected by the changes until it's updated to import std.datetime.stopwatch, +and when the old symbols are finally removed, the selective imports and fully +qualified paths to the new symbols will continue to work and won't break +(though at that point, simply importing std.datetime will work, since +std.datetime.package will have been updated to publicly import +std.datetime.stopwatch). Code that simply imporst std.datetime.stopwatch without +importing std.datetime will not have to worry about symbol conflicts. From dfd7de87778c18f432c45d7577a04ac6b17b643a Mon Sep 17 00:00:00 2001 From: Jonathan M Davis Date: Sun, 7 May 2017 01:16:25 +0200 Subject: [PATCH 3/4] Update changelog entry to use MREF instead of LINK2. --- changelog/split-std-datetime.dd | 55 ++++++++++++++------------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/changelog/split-std-datetime.dd b/changelog/split-std-datetime.dd index 5e6f9b67578..656979a6cac 100644 --- a/changelog/split-std-datetime.dd +++ b/changelog/split-std-datetime.dd @@ -3,46 +3,39 @@ std.datetime has been split into a package. std.datetime is now a package containing the following modules: $(UL - $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_date.html, std.datetime.date)) - $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_interval.html, std.datetime.interval)) - $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_stopwatch.html, std.datetime.stopwatch)) - $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_systime.html, std.datetime.systime)) - $(LI $(LINK2 $(PHOBOS_PATH)std_datetime_timezone.html, std.datetime.timezone)) + $(LI $(MREF std,datetime,date)) + $(LI $(MREF std,datetime,interval)) + $(LI $(MREF std,datetime,stopwatch)) + $(LI $(MREF std,datetime,systime)) + $(LI $(MREF std,datetime,timezone)) ) -$(LINK2 $(PHOBOS_PATH)std_datetime.html, std.datetime.package) publicly imports -all of those modules. So, it should be the case that no existing code will -break, as everything in std.datetime will still be imported by importing -std.datetime. New code can choose to import the modules individually or to -import the entire package. +$(MREF std,datetime,package) publicly imports all of those modules. So, it +should be the case that no existing code will break, as everything in +std.datetime will still be imported by importing std.datetime. New code can +choose to import the modules individually or to import the entire package. -$(LINK2 $(PHOBOS_PATH)std_datetime_date.html, std.datetime.date) contains Date, -TimeOfDay, DateTime, and the related free functions. It also contains -DateTimeException. +$(MREF std,datetime,date) contains Date, TimeOfDay, DateTime, and the related +free functions. It also contains DateTimeException. -$(LINK2 $(PHOBOS_PATH)std_datetime_interval.html, std.datetime.interval) -contains the *Interval and *IntervalRange types as well as the related free -functions. +$(MREF std,datetime,interval) contains the *Interval and *IntervalRange types +as well as the related free functions. -$(LINK2 $(PHOBOS_PATH)std_datetime_systime.html, std.datetime.systime) -contains SysTime and the related free functions. +$(MREF std,datetime,systime) contains SysTime and the related free functions. -$(LINK2 $(PHOBOS_PATH)std_datetime_timezone.html, std.datetime.timezone) -contains the time zone types. +$(MREF std,datetime,timezone) contains the time zone types. -$(LINK2 $(PHOBOS_PATH)std_datetime.html, std.datetime.package) contains -StopWatch and the benchmarking functions (so, they can only be imported via -std.datetime and not via a submodule). As those functions use -$(REF TickDuration,core,time) (which is being replaced by +$(MREF std,datetime,package) contains StopWatch and the benchmarking functions +(so, they can only be imported via std.datetime and not via a submodule). As +those functions use $(REF TickDuration,core,time) (which is being replaced by $(REF MonoTime,core,time), they are slated for deprecation. -$(LINK2 $(PHOBOS_PATH)std_datetime_stopwatch.html, std.datetime.stopwatch) has -been added. It contains versions of StopWatch and benchmark which have almost -the same API as the existing symbols, but they use $(REF MonoTime,core,time) and -$(REF Duration,core,time) instead of $(REF TickDuration,core,time). In the next -major release, the old functions in std.datetime.package will be deprecated, so -code which uses the old benchmarking functions should be updated to use -std.datetime.stopwatch. +$(MREF std,datetime,stopwatch) has been added. It contains versions of +StopWatch and benchmark which have almost the same API as the existing symbols, +but they use $(REF MonoTime,core,time) and $(REF Duration,core,time) instead of +$(REF TickDuration,core,time). In the next major release, the old functions in +std.datetime.package will be deprecated, so code which uses the old +benchmarking functions should be updated to use std.datetime.stopwatch. However, note that in order to avoid irreconcilable symbol conflicts between the new and old versions, std.datetime.stopwatch will not be publicly imported From 90971797e6956c301ebf0d2a996e2a6888cce3ac Mon Sep 17 00:00:00 2001 From: Jonathan M Davis Date: Sun, 7 May 2017 01:21:30 +0200 Subject: [PATCH 4/4] Warn about impending deprecation of functions in std.datetime.package. --- std/datetime/package.d | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/std/datetime/package.d b/std/datetime/package.d index 82611bc8d66..9395590a002 100644 --- a/std/datetime/package.d +++ b/std/datetime/package.d @@ -170,6 +170,12 @@ alias AutoStart = Flag!"autoStart"; /++ + $(RED This will be deprecated in 2.076. Please use + $(REF StopWatch,std,datetime,stopwatch) instead. It uses + $(REF Monotime,core,time) and $(REF Duration,core,time) rather + than $(REF TickDuration,core,time), which will also be deprecated in + 2.076.) + $(D StopWatch) measures time as precisely as possible. This class uses a high-performance counter. On Windows systems, it uses @@ -416,6 +422,12 @@ private: /++ + $(RED This will be deprecated in 2.076. Please use + $(REF benchmark,std,datetime,stopwatch) instead. It uses + $(REF Monotime,core,time) and $(REF Duration,core,time) rather + than $(REF TickDuration,core,time), which will also be deprecated in + 2.076.) + Benchmarks code for speed assessment and comparison. Params: @@ -526,6 +538,12 @@ private: /++ + $(RED This will be deprecated in 2.076. Please use + $(REF benchmark,std,datetime,stopwatch) instead. This function has + not been ported to $(REF Monotime,core,time) and + $(REF Duration,core,time), because it is a trivial wrapper around + benchmark.) + Benchmark with two functions comparing. Params: @@ -568,6 +586,12 @@ ComparingBenchmarkResult comparingBenchmark(alias baseFunc, /++ + $(RED This will be deprecated in 2.076. Please use + $(REF StopWatch,std,datetime,stopwatch) instead. This function has + not been ported to $(REF Monotime,core,time) and + $(REF Duration,core,time), because it is a trivial wrapper around + StopWatch.) + Function for starting to a stop watch time when the function is called and stopping it when its return value goes out of scope and is destroyed.