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/src')
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
+
+
+
+