84 time
%--------------------------------------------------%
% vim: ft=mercury ts=4 sw=4 et wm=0 tw=0
%--------------------------------------------------%
% Originally written in 1999 by Tomas By <T.By@dcs.shef.ac.uk>
% "Feel free to use this code or parts of it any way you want."
%
% Some portions are Copyright (C) 1999-2007,2009-2012 The University of Melbourne.
% This file may only be copied under the terms of the GNU Library General
% Public License - see the file COPYING.LIB in the Mercury distribution.
%--------------------------------------------------%
%
% File: time.m.
% Main authors: Tomas By <T.By@dcs.shef.ac.uk>, fjh.
% Stability: medium.
%
% Time functions.
%
%--------------------------------------------------%
%--------------------------------------------------%
:- module time.
:- interface.
:- import_module io.
:- import_module maybe.
%--------------------------------------------------%
% The `clock_t' type represents times measured in clock ticks.
% NOTE: the unit used for a value of this type depends on whether it was
% returned by `time.clock' or `time.times'. See the comments on these
% predicates below.
%
:- type clock_t == int.
% The `tms' type holds information about the amount of processor
% time that a process and its child processes have consumed.
%
:- type tms
---> tms(
clock_t, % tms_utime: user time
clock_t, % tms_stime: system time
clock_t, % tms_cutime: user time of children
clock_t % tms_cstime: system time of children
).
% The `time_t' type is an abstract type that represents
% calendar times.
%
:- type time_t.
% The `tm' type is a concrete type that represents calendar
% times, broken down into their constituent components.
% Comparison (via compare/3) of `tm' values whose `tm_dst'
% components are identical is equivalent to comparison of
% the times those `tm' values represent.
%
:- type tm
---> tm(
tm_year :: int, % Year (number since 1900)
tm_mon :: int, % Month (number since January, 0-11)
tm_mday :: int, % MonthDay (1-31)
tm_hour :: int, % Hours (after midnight, 0-23)
tm_min :: int, % Minutes (0-59)
tm_sec :: int, % Seconds (0-61)
% (60 and 61 are for leap seconds)
tm_yday :: int, % YearDay (number since Jan 1st, 0-365)
tm_wday :: int, % WeekDay (number since Sunday, 0-6)
tm_dst :: maybe(dst) % IsDST (is DST in effect?)
).
:- type dst
---> standard_time % no, DST is not in effect
; daylight_time. % yes, DST is in effect
% Some of the procedures in this module throw this type
% as an exception if they can't obtain a result.
%
:- type time_error
---> time_error(string). % Error message
%--------------------------------------------------%
% time.clock(Result, !IO):
%
% Returns the elapsed processor time (number of clock ticks). The base time
% is arbitrary but doesn't change within a single process. If the time
% cannot be obtained, this procedure will throw a time_error exception.
% To obtain a time in seconds, divide Result by `time.clocks_per_sec'.
%
% On Java the elapsed time for the calling thread is returned.
%
:- pred time.clock(clock_t::out, io::di, io::uo) is det.
% time.clocks_per_sec:
%
% Returns the number of "clocks" per second as defined by CLOCKS_PER_SEC.
% A `clock_t' value returned by `time.clock' can be divided by this value
% to obtain a time in seconds. Note that the value of this function does
% not necessarily reflect the actual clock precision; it just indicates the
% scaling factor for the results of time.clock.
%
:- func time.clocks_per_sec = int.
%--------------------------------------------------%
% time.time(Result, !IO):
%
% Returns the current (simple) calendar time. If the time cannot be
% obtained, this procedure will throw a time_error exception.
%
:- pred time.time(time_t::out, io::di, io::uo) is det.
%--------------------------------------------------%
% time.times(ProcessorTime, ElapsedRealTime, !IO):
%
% (POSIX)
%
% Returns the processor time information in the `tms' value, and the
% elapsed real time relative to an arbitrary base in the `clock_t' value.
% To obtain a time in seconds, divide the result by `time.clk_tck'.
% If the time cannot be obtained, this procedure will throw a time_error
% exception.
%
% On non-POSIX systems that do not support this functionality,
% this procedure may simply always throw an exception.
%
% On Java the times for the calling thread are returned.
% On Win32 and Java the child part of 'tms' is always zero.
%
:- pred time.times(tms::out, clock_t::out, io::di, io::uo) is det.
% time.clk_tck:
%
% Returns the number of "clock ticks" per second as defined by
% sysconf(_SC_CLK_TCK). A `clock_t' value returned by `time.times'
% can be divided by this value to obtain a time in seconds.
%
% On non-POSIX systems that do not support this functionality,
% this procedure may simply always throw an exception.
%
:- func time.clk_tck = int.
%--------------------------------------------------%
% time.difftime(Time1, Time0) = Diff:
%
% Computes the number of seconds elapsed between `Time1' and `Time0'.
%
:- func time.difftime(time_t, time_t) = float.
% time.localtime(Time) = TM:
%
% Converts the calendar time `Time' to a broken-down representation,
% expressed relative to the user's specified time zone.
%
:- func time.localtime(time_t) = tm.
% time.gmtime(Time) = TM:
%
% Converts the calendar time `Time' to a broken-down representation,
% expressed as UTC (Universal Coordinated Time).
%
:- func time.gmtime(time_t) = tm.
% time.mktime(TM) = Time:
%
% Converts the broken-down local time value to calendar time.
% It also normalises the value by filling in day of week and day of year
% based on the other components.
%
:- func time.mktime(tm) = time_t.
%--------------------------------------------------%
% time.asctime(TM) = String:
%
% Converts the broken-down time value `TM' to a string in a standard
% format.
%
:- func time.asctime(tm) = string.
% time.ctime(Time) = String:
%
% Converts the calendar time value `Time' to a string in a standard format
% (i.e. same as "asctime (localtime (<time>))").
%
:- func time.ctime(time_t) = string.
%--------------------------------------------------%
%--------------------------------------------------%