From 858c6f7fa44f7b2dc363b359198d6522dd60e914 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Tue, 5 Jan 2016 16:55:04 +0100 Subject: Introduce time warp safe trace timestamp formats New timestamp options for trace, sequential trace, and system profile: - monotonic_timestamp - strict_monotonic_timestamp --- erts/doc/src/erlang.xml | 64 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 60 insertions(+), 4 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 64eebec936..79d3f66ea8 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -7739,6 +7739,13 @@ ok inactive, and later active when the port callback returns.

+ monotonic_timestamp + +

Timestamps in profile messages will use + Erlang + monotonic time. The time-stamp (Ts) has the same + format and value as produced by erlang:monotonic_time().

+ runnable_procs

If a process is put into or removed from the run queue, a @@ -7759,6 +7766,25 @@ ok {profile, scheduler, Id, State, NoScheds, Ts}, is sent to ProfilerPid.

 + strict_monotonic_timestamp + +

Timestamps in profile messages will consisting of + Erlang + monotonic time and a monotonically increasing + integer. The time-stamp (Ts) has the same format and value + as produced by {erlang:monotonic_time(), + erlang:unique_integer([monotonic])}.

+ + timestamp + +

Timestamps in profile messages will include a + time-stamp (Ts) that has the same form as returned by + erlang:now(). This is also the default if no + timestamp flag is given. If cpu_timestamp has + been enabled via erlang:trace/3, this will also + effect the timestamp produced in profiling messages + when timestamp flag is enabled.

+

erlang:system_profile is considered experimental and its behavior can change in a future release.

@@ -8118,7 +8144,10 @@ timestamp() -> cpu_timestamp

A global trace flag for the Erlang node that makes all - trace time-stamps to be in CPU time, not wall clock time. + trace time-stamps using the timestamp flag to be + in CPU time, not wall clock time. That is, cpu_timestamp + will not be used if monotonic_timestamp, or + strict_monotonic_timestamp is enabled. Only allowed with PidSpec==all. If the host machine OS does not support high-resolution CPU time measurements, trace/3 exits with @@ -8126,6 +8155,26 @@ timestamp() -> not synchronize this value across cores, so be prepared that time might seem to go backwards when using this option.

 + monotonic_timestamp + +

Includes an + Erlang + monotonic time time-stamp in all trace messages. The + time-stamp (Ts) has the same format and value as produced by + erlang:monotonic_time(). This flag overrides + the cpu_timestamp flag.

+ + strict_monotonic_timestamp + +

Includes an timestamp consisting of + Erlang + monotonic time and a monotonically increasing + integer in all trace messages. The time-stamp (Ts) has the + same format and value as produced by + {erlang:monotonic_time(), + erlang:unique_integer([monotonic])}. This flag overrides + the cpu_timestamp flag.

+ arity

Used with the call trace flag. @@ -8172,9 +8221,16 @@ timestamp() -> in the following list. Pid is the process identifier of the traced process in which the traced event has occurred. The third tuple element is the message tag.

-

If flag timestamp is given, the first tuple - element is trace_ts instead, and the time-stamp - is added last in the message tuple.

+

If flag timestamp, strict_monotonic_timestamp, or + monotonic_timestamp is given, the first tuple + element is trace_ts instead, and the time-stamp + is added as an extra element last in the message tuple. If + multiple timestamp flags are passed, timestamp has + precedence over strict_monotonic_timestamp which + in turn has precedence over monotonic_timestamp. All + timestamp flags are remembered, so if two are passed + and the one with highest precedence later is disabled + the other one will become active.

{trace, Pid, 'receive', Msg} -- cgit v1.2.3 From 3f33428db9aea0d767295322c4e882a5c6bbf7db Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Tue, 19 Jan 2016 17:05:55 +0100 Subject: Introduce time management in native APIs --- erts/doc/src/erl_driver.xml | 112 ++++++++++++++++++++++++++++++++++++++++++++ erts/doc/src/erl_nif.xml | 112 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index e717fc0c4e..e338e95938 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -347,6 +347,16 @@ the driver does not handle sizes that overflow an int all will work as before.

 + Time Measurement +

Support for time measurement in drivers: + + ErlDrvTime + ErlDrvTimeUnit + erl_drv_monotonic_time() + erl_drv_time_offset() + erl_drv_convert_time_unit() +

+ @@ -860,6 +870,24 @@ typedef struct ErlIOVec { erl_drv_tsd_get().

+ ErlDrvTime + +

A signed 64-bit integer type for representation of time.

+ + ErlDrvTimeUnit + +

An enumeration of time units supported by the driver API:

+ + ERL_DRV_SEC +

Seconds

 + ERL_DRV_MSEC +

Milliseconds

 + ERL_DRV_USEC +

Microseconds

 + ERL_DRV_NSEC +

Nanoseconds

 + + @@ -1023,6 +1051,10 @@ typedef struct ErlIOVec { Read a system timestamp +

This function is deprecated! Do not use it! + Use the documented + time measurement functionality + instead.

This function reads a timestamp into the memory pointed to by the parameter now. See the description of ErlDrvNowData for specification of its fields.

@@ -2997,6 +3029,86 @@ ERL_DRV_MAP int sz + + ErlDrvTimeerl_drv_monotonic_time(ErlDrvTimeUnit time_unit) + Get Erlang Monotonic Time + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

+ Returns + Erlang + monotonic time. Note that it is not uncommon with + negative values. +

+

Returns ERL_DRV_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlDrvTime + ErlDrvTimeUnit + + + + + + ErlDrvTimeerl_drv_time_offset(ErlDrvTimeUnit time_unit) + Get current Time Offset + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

Returns the current time offset between + Erlang monotonic time + and + Erlang system time + converted into the time_unit passed as argument.

+

Returns ERL_DRV_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlDrvTime + ErlDrvTimeUnit + + + + + + ErlDrvTimeerl_drv_convert_time_unit(ErlDrvTime val, ErlDrvTimeUnit from, ErlDrvTimeUnit to) + Convert time unit of a time value + + +

Arguments:

+ + val + Value to convert time unit for. + from + Time unit of val. + to + Time unit of returned value. + +

Converts the val value of time unit from to + the corresponding value of time unit to. The result is + rounded using the floor function.

+

Returns ERL_DRV_TIME_ERROR if called with an invalid + time unit argument.

+

See also:

+ + ErlDrvTime + ErlDrvTimeUnit + + + +
SEE ALSO diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 2d8706169f..420c9fea38 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -317,6 +317,17 @@ ok libraries might however fail if deprecated features are used.

+ Time Measurement +

Support for time measurement in NIF libraries: + + ErlNifTime + ErlNifTimeUnit + enif_monotonic_time() + enif_time_offset() + enif_convert_time_unit() +

+ + Long-running NIFs

Native functions @@ -560,6 +571,25 @@ typedef enum {

A native signed 64-bit integer type.

 ErlNifUInt64

A native unsigned 64-bit integer type.

 + + ErlNifTime + +

A signed 64-bit integer type for representation of time.

+ + ErlNifTimeUnit + +

An enumeration of time units supported by the NIF API:

+ + ERL_NIF_SEC +

Seconds

 + ERL_NIF_MSEC +

Milliseconds

 + ERL_NIF_USEC +

Microseconds

 + ERL_NIF_NSEC +

Nanoseconds

 + +
@@ -1486,6 +1516,88 @@ enif_map_iterator_destroy(env, &iter);

Same as erl_drv_tsd_set.

+ + + + ErlNifTimeenif_monotonic_time(ErlNifTimeUnit time_unit) + Get Erlang Monotonic Time + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

+ Returns + Erlang + monotonic time. Note that it is not uncommon with + negative values. +

+

Returns ERL_NIF_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlNifTime + ErlNifTimeUnit + + + + + + ErlNifTimeenif_time_offset(ErlNifTimeUnit time_unit) + Get current Time Offset + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

Returns the current time offset between + Erlang monotonic time + and + Erlang system time + converted into the time_unit passed as argument.

+

Returns ERL_NIF_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlNifTime + ErlNifTimeUnit + + + + + + ErlNifTimeenif_convert_time_unit(ErlNifTime val, ErlNifTimeUnit from, ErlNifTimeUnit to) + Convert time unit of a time value + + +

Arguments:

+ + val + Value to convert time unit for. + from + Time unit of val. + to + Time unit of returned value. + +

Converts the val value of time unit from to + the corresponding value of time unit to. The result is + rounded using the floor function.

+

Returns ERL_NIF_TIME_ERROR if called with an invalid + time unit argument.

+

See also:

+ + ErlNifTime + ErlNifTimeUnit + + + +
SEE ALSO -- cgit v1.2.3