View Source Membrane.Time (Membrane Core v1.0.0)

Module containing functions needed to perform handling of time.

Membrane always internally uses nanosecond as a time unit. This is how all time units should represented in the code unless there's a good reason to act differently.

Please note that Erlang VM may internally use different units and that may differ from platform to platform. Still, unless you need to perform calculations that do not touch hardware clock, you should use Membrane units for consistency.

Summary

Types

t()

The time represented in Membrane's time units.

Functions

Returns time in days.

Returns time in hours.

Returns time in microseconds.

Returns time in milliseconds.

Returns time in minutes.

Returns time in nanoseconds.

Returns time in seconds.

Returns one day in Membrane.Time units.

Returns given amount of days in Membrane.Time units.

Divides timestamp by a timebase. The result is rounded to the nearest integer.

Converts iso8601 string to Membrane.Time units. If value is invalid, throws match error.

Converts NTP timestamp (time since 0h on 1st Jan 1900) into Unix timestamp (time since 1st Jan 1970) represented in Membrane.Time units.

Returns one hour in Membrane.Time units.

Returns given amount of hours in Membrane.Time units.

Returns string representation of result of to_code/1.

Checks whether a value is Membrane.Time.t.

Returns one microsecond in Membrane.Time units.

Returns given amount of microseconds in Membrane.Time units.

Returns one millisecond in Membrane.Time units.

Returns given amount of milliseconds in Membrane.Time units.

Returns one minute in Membrane.Time units.

Returns given amount of minutes in Membrane.Time units.

Returns current monotonic time based on System.monotonic_time/0 in Membrane.Time units.

Returns one nanosecond in Membrane.Time units.

Returns given amount of nanoseconds in Membrane.Time units.

Returns one VM native unit in Membrane.Time units.

Returns given amount of VM native units in Membrane.Time units.

Returns current POSIX time of operating system based on System.os_time/0 in Membrane.Time units.

Returns duration as a string with unit. Chosen unit is the biggest possible that doesn't involve precission loss.

Returns current time in pretty format (currently iso8601), as string Uses os_time/0 under the hood.

Returns one second in Membrane.Time units.

Returns given amount of seconds in Membrane.Time units.

Returns quoted code producing given amount time. Chosen unit is the biggest possible that doesn't involve precission loss.

Returns time as a DateTime struct. TimeZone is set to UTC.

Returns time as a iso8601 string.

Returns time in VM native units. Rounded using Kernel.round/1.

Converts the timestamp into NTP timestamp. May introduce small rounding errors.

Returns current Erlang VM system time based on System.system_time/0 in Membrane.Time units.

Types

@type non_neg() :: non_neg_integer()
@type t() :: integer()

The time represented in Membrane's time units.

Functions

Link to this function

as_days(time, mode \\ :exact)

View Source
@spec as_days(t(), mode :: :round | :exact) :: integer() | Ratio.t()

Returns time in days.

If the mode argument is set to :exact (default), the result is represented as a rational number. Otherwise, if the mode is :round, the result is rounded to the nearest integer.

Link to this function

as_hours(time, mode \\ :exact)

View Source
@spec as_hours(t(), mode :: :round | :exact) :: integer() | Ratio.t()

Returns time in hours.

If the mode argument is set to :exact (default), the result is represented as a rational number. Otherwise, if the mode is :round, the result is rounded to the nearest integer.

Link to this function

as_microseconds(time, mode \\ :exact)

View Source
@spec as_microseconds(t(), mode :: :round | :exact) :: integer() | Ratio.t()

Returns time in microseconds.

If the mode argument is set to :exact (default), the result is represented as a rational number. Otherwise, if the mode is :round, the result is rounded to the nearest integer.

Link to this function

as_milliseconds(time, mode \\ :exact)

View Source
@spec as_milliseconds(t(), mode :: :round | :exact) :: integer() | Ratio.t()

Returns time in milliseconds.

If the mode argument is set to :exact (default), the result is represented as a rational number. Otherwise, if the mode is :round, the result is rounded to the nearest integer.

Link to this function

as_minutes(time, mode \\ :exact)

View Source
@spec as_minutes(t(), mode :: :round | :exact) :: integer() | Ratio.t()

Returns time in minutes.

If the mode argument is set to :exact (default), the result is represented as a rational number. Otherwise, if the mode is :round, the result is rounded to the nearest integer.

Link to this function

as_nanoseconds(time, mode \\ :exact)

View Source
@spec as_nanoseconds(t(), mode :: :round | :exact) :: integer() | Ratio.t()

Returns time in nanoseconds.

If the mode argument is set to :exact (default), the result is represented as a rational number. Otherwise, if the mode is :round, the result is rounded to the nearest integer.

Link to this function

as_seconds(time, mode \\ :exact)

View Source
@spec as_seconds(t(), mode :: :round | :exact) :: integer() | Ratio.t()

Returns time in seconds.

If the mode argument is set to :exact (default), the result is represented as a rational number. Otherwise, if the mode is :round, the result is rounded to the nearest integer.

@spec day() :: t()

Returns one day in Membrane.Time units.

@spec days(integer() | Ratio.t()) :: t()

Returns given amount of days in Membrane.Time units.

Link to this function

divide_by_timebase(timestamp, timebase)

View Source
@spec divide_by_timebase(number() | Ratio.t(), number() | Ratio.t()) :: integer()

Divides timestamp by a timebase. The result is rounded to the nearest integer.

Examples:

iex> timestamp = 10 |> Membrane.Time.seconds()
iex> timebase = Ratio.new(Membrane.Time.second(), 30)
iex> Membrane.Time.divide_by_timebase(timestamp, timebase)
300
@spec from_datetime(DateTime.t()) :: t()

Converts DateTime to Membrane.Time units.

@spec from_iso8601!(String.t()) :: t()

Converts iso8601 string to Membrane.Time units. If value is invalid, throws match error.

@spec from_ntp_timestamp(ntp_time :: <<_::64>>) :: t()

Converts NTP timestamp (time since 0h on 1st Jan 1900) into Unix timestamp (time since 1st Jan 1970) represented in Membrane.Time units.

NTP timestamp uses fixed point representation with the integer part in the first 32 bits and the fractional part in the last 32 bits.

@spec hour() :: t()

Returns one hour in Membrane.Time units.

@spec hours(integer() | Ratio.t()) :: t()

Returns given amount of hours in Membrane.Time units.

@spec inspect(t()) :: String.t()

Returns string representation of result of to_code/1.

Link to this macro

is_time(value)

View Source (macro)

Checks whether a value is Membrane.Time.t.

@spec microsecond() :: t()

Returns one microsecond in Membrane.Time units.

@spec microseconds(integer() | Ratio.t()) :: t()

Returns given amount of microseconds in Membrane.Time units.

@spec millisecond() :: t()

Returns one millisecond in Membrane.Time units.

@spec milliseconds(integer() | Ratio.t()) :: t()

Returns given amount of milliseconds in Membrane.Time units.

@spec minute() :: t()

Returns one minute in Membrane.Time units.

@spec minutes(integer() | Ratio.t()) :: t()

Returns given amount of minutes in Membrane.Time units.

@spec monotonic_time() :: t()

Returns current monotonic time based on System.monotonic_time/0 in Membrane.Time units.

@spec nanosecond() :: t()

Returns one nanosecond in Membrane.Time units.

@spec nanoseconds(integer() | Ratio.t()) :: t()

Returns given amount of nanoseconds in Membrane.Time units.

@spec native_unit() :: t()

Returns one VM native unit in Membrane.Time units.

@spec native_units(integer()) :: t()

Returns given amount of VM native units in Membrane.Time units.

@spec os_time() :: t()

Returns current POSIX time of operating system based on System.os_time/0 in Membrane.Time units.

This time is not monotonic.

@spec pretty_duration(t()) :: String.t()

Returns duration as a string with unit. Chosen unit is the biggest possible that doesn't involve precission loss.

Examples

iex> import Membrane.Time
iex> 10 |> milliseconds() |> pretty_duration()
"10 ms"
iex> 60_000_000 |> microseconds() |> pretty_duration()
"1 min"
iex> 2 |> nanoseconds() |> pretty_duration()
"2 ns"
@spec pretty_now() :: String.t()

Returns current time in pretty format (currently iso8601), as string Uses os_time/0 under the hood.

@spec second() :: t()

Returns one second in Membrane.Time units.

@spec seconds(integer() | Ratio.t()) :: t()

Returns given amount of seconds in Membrane.Time units.

@spec to_code(t()) :: Macro.t()

Returns quoted code producing given amount time. Chosen unit is the biggest possible that doesn't involve precission loss.

Examples

iex> import Membrane.Time
iex> 10 |> milliseconds() |> to_code() |> Macro.to_string()
quote do 10 |> Membrane.Time.milliseconds() end |> Macro.to_string()
iex> 60_000_000 |> microseconds() |> to_code() |> Macro.to_string()
quote do Membrane.Time.minute() end |> Macro.to_string()
iex> 2 |> nanoseconds() |> to_code() |> Macro.to_string()
quote do 2 |> Membrane.Time.nanoseconds() end |> Macro.to_string()
@spec to_datetime(t()) :: DateTime.t()

Returns time as a DateTime struct. TimeZone is set to UTC.

@spec to_iso8601(t()) :: String.t()

Returns time as a iso8601 string.

@spec to_native_units(t()) :: integer()

Returns time in VM native units. Rounded using Kernel.round/1.

Link to this function

to_ntp_timestamp(timestamp)

View Source
@spec to_ntp_timestamp(timestamp :: t()) :: <<_::64>>

Converts the timestamp into NTP timestamp. May introduce small rounding errors.

@spec vm_time() :: t()

Returns current Erlang VM system time based on System.system_time/0 in Membrane.Time units.

It is the VM view of the os_time/0. They may not match in case of time warps. It is not monotonic.