Система

Модуль System предоставляет функции, которые взаимодействуют напрямую с виртуальной машиной или хостовой системой.

Время

Модуль System также предоставляет функции, работающие со временем, возвращая различные значения времени, хранимые системой, с поддержкой разных единиц измерения времени.

Одна из сложностей, связанных с использованием системного времени, заключается в том, что оно может быть скорректировано. Например, при переходе на летнее/зимнее время системные часы корректируются, часто добавляя или убирая один час. Такие изменения называются «временными скачками». Чтобы понять, как такие изменения могут быть вредными, рассмотрим следующий код:

## DO NOT DO THIS
prev = System.os_time()
# ... execute some code ...
next = System.os_time()
diff = next - prev

Если во время выполнения кода системные часы изменяются, некоторые действия, выполненные за 1 секунду, могут быть отображены как занявшие более 1 часа! Для решения таких проблем виртуальная машина предоставляет монотонное время через System.monotonic_time/0, которое никогда не уменьшается и не претерпевает скачков:

## DO THIS
prev = System.monotonic_time()
# ... execute some code ...
next = System.monotonic_time()
diff = next - prev

В общем случае, виртуальная машина предоставляет три измерения времени:

• os_time/0 - время, отчётное операционной системой. Это время может быть скорректировано вперёд или назад без ограничений;

• system_time/0 - представление виртуальной машины о os_time/0. Системное время и время ОС могут не совпадать в случае временных скачков, хотя виртуальная машина стремится их согласовать. Это время не монотонно (т.е. может уменьшаться), так как его поведение настраивается режимом временных скачков виртуальной машины;

• monotonic_time/0 - монотонно возрастающее время, предоставляемое виртуальной машиной Erlang.

Функции времени в этом модуле работают в :native единице (если не указано иное), которая зависит от операционной системы. В большинстве случаев все вычисления выполняются в :native единице, чтобы избежать потери точности, с вызовом convert_time_unit/3 в конце для преобразования в определённую единицу измерения, например, :millisecond или :microsecond. См. тип time_unit/0 для получения дополнительной информации.

Для более подробного ознакомления с поддержкой разных типов времени виртуальной машиной см. главу о времени и корректировке времени в документации Erlang.

Сводка

Типы

time_unit()

Единица измерения времени, которая должна передаваться функциям, таким как monotonic_time/1 и другим

Функции

argv()

Список аргументов командной строки

argv(args)

Изменение аргументов командной строки

at_exit(fun)

Регистрация обработчика завершения программы

build_info()

Информация о сборке Elixir

cmd(command, args, opts \\ [])

Выполнение заданной command с args

compiled_endianness()

Возвращает порядок байтов, с которым была скомпилирована система

convert_time_unit(time, from_unit, to_unit)

Преобразует time из единицы измерения времени from_unit в единицу измерения времени to_unit

cwd()

Текущая рабочая директория

cwd!()

Текущая рабочая директория, исключение при ошибке

delete_env(varname)

Удаляет переменную среды

endianness()

Возвращает порядок байтов

find_executable(program)

Определяет исполняемый файл в системе

get_env()

Переменные среды системы

get_env(varname)

Значение переменной среды

get_pid()

Идентификатор процесса виртуальной машины Erlang

halt(status \\ 0)

Останавливает систему выполнения Erlang

monotonic_time()

Возвращает текущее монотонное время в :native единице измерения времени

monotonic_time(unit)

Возвращает текущее монотонное время в заданной единице измерения времени

os_time()

Возвращает текущее время ОС

os_time(unit)

Возвращает текущее время ОС в заданной единице измерения unit

otp_release()

Возвращает номер версии OTP

put_env(enum)

Устанавливает несколько переменных среды

put_env(varname, value)

Устанавливает значение переменной среды

schedulers()

Возвращает количество планировщиков в виртуальной машине

schedulers_online()

Возвращает количество активных планировщиков в виртуальной машине

stacktrace()

Последний стек исключений

system_time()

Возвращает текущее системное время в :native единице измерения времени

system_time(unit)

Возвращает текущее системное время в заданной единице измерения времени

time_offset()

Возвращает текущий временной сдвиг между монотонным временем виртуальной машины Erlang и системным временем виртуальной машины Erlang

time_offset(unit)

Возвращает текущий временной сдвиг между монотонным временем виртуальной машины Erlang и системным временем виртуальной машины Erlang

tmp_dir()

Директория временных файлов для записи

tmp_dir!()

Директория временных файлов для записи, исключение при ошибке

unique_integer(modifiers \\ [])

Генерирует и возвращает уникальное целое число в текущем экземпляре приложения

user_home()

Домашняя директория пользователя

user_home!()

Домашняя директория пользователя, исключение при ошибке

version()

Информация о версии Elixir

Типы

time_unit()

time_unit() ::
  :second |
  :millisecond |
  :microsecond |
  :nanosecond |
  pos_integer() |
  :seconds |
  :milliseconds |
  :microseconds |
  :nanoseconds

Единица измерения времени, которая должна передаваться функциям, таким как monotonic_time/1 и другим.

Единицы измерения времени :second, :millisecond, :microsecond и :nanosecond контролируют возвращаемое значение функций, которые принимают единицу измерения времени.

Единица измерения времени также может быть строго положительным целым числом. В этом случае оно представляет собой «части на секунду»: время будет возвращено в 1 / parts_per_second секундах. Например, использование единицы измерения времени :millisecond эквивалентно использованию 1000 в качестве единицы измерения времени (так как время будет возвращено в 1/1000 секунды - миллисекундах).

Обратите внимание, что API Erlang до версии 19.1 будет использовать :milli_seconds, :micro_seconds и :nano_seconds в качестве единиц измерения времени, хотя Elixir нормализует их написание в соответствии с международной системой единиц.

Функции

argv()

argv() :: [String.t()]

Список аргументов командной строки.

Возвращает список аргументов командной строки, переданных программе.

argv(args)

argv([String.t()]) :: :ok

Изменение аргументов командной строки.

Изменяет список аргументов командной строки. Используйте с осторожностью, так как он уничтожает любую предыдущую информацию argv.

at_exit(fun)

Регистрация обработчика завершения программы.

Регистрирует функцию, которая будет вызвана по завершении выполнения программы. Полезно для вызова обработчика в режиме «скрипт».

Обработчик всегда выполняется в другом процессе, отличном от того, в котором он был зарегистрирован. Вследствие этого любые ресурсы, управляемые вызывающим процессом (таблицы ETS, открытые файлы и т.д.), не будут доступны к моменту вызова функции обработчика.

Функция должна принимать код завершения в качестве аргумента.

build_info()

build_info() :: map()

Информация о сборке Elixir.

Возвращает список ключевых слов с версией Elixir, коротким хэшем Git-ревизии и датой компиляции.

cmd(command, args, opts \\ [])

cmd(binary(), [binary()], Keyword.t()) :: {Collectable.t(), exit_status :: non_neg_integer()}

Выполняет заданную command с args.

command ожидается, что это исполняемый файл, доступный в PATH, если не указан абсолютный путь.

args должен быть списком бинарных файлов, которые исполняемый файл получит в качестве своих аргументов как есть. Это означает, что:

• переменные среды не будут интерполированы
• расширение шаблонов не будет происходить (если Path.wildcard/2 не используется явно)
• аргументы не нужно экранировать или заключать в кавычки для безопасности оболочки

Эта функция возвращает кортеж, содержащий собранный результат и код завершения команды.

Внутри эта функция использует Port для взаимодействия с внешним миром. Однако, если вы планируете запускать долго выполняющуюся программу, порты гарантируют, что устройства stdin/stdout будут закрыты, но это не приводит к автоматическому завершению задачи. В документации по модулю Port эта проблема и возможные решения описаны в разделе «Процессы-зомби».

Примеры

iex> System.cmd "echo", ["hello"]
{"hello\n", 0}

iex> System.cmd "echo", ["hello"], env: [{"MIX_ENV", "test"}]
{"hello\n", 0}

iex> System.cmd "echo", ["hello"], into: IO.stream(:stdio, :line)
hello
{%IO.Stream{}, 0}

Параметры

• :into — вставляет результат в указанный объект сбора, по умолчанию ""
• :cd — каталог для выполнения команды
• :env — перечислитель кортежей, содержащих имя и значение переменной среды в виде бинарных данных
• :arg0 — устанавливает arg0 команды
• :stderr_to_stdout — перенаправляет stderr в stdout, когда true
• :parallelism — когда true, виртуальная машина будет планировать задачи порта для повышения параллелизма в системе. Если установлено значение false, виртуальная машина попытается выполнить команды немедленно, улучшив время отклика за счёт снижения параллелизма. Значение по умолчанию можно установить при запуске системы, передав аргумент «+spp» в --erl.

Причины ошибок

Если указаны неверные аргументы, ArgumentError генерируется System.cmd/3. System.cmd/3 также ожидает строго определённый набор параметров и генерирует ошибку, если указаны неизвестные или некорректные параметры.

Кроме того, System.cmd/3 может завершиться ошибкой по одной из POSIX-причин, описанных ниже:

• :system_limit — все доступные порты в эмуляторе Erlang заняты

• :enomem — не хватило памяти для создания порта

• :eagain — больше нет доступных процессов операционной системы

• :enametoolong — внешняя команда оказалась слишком длинной

• :emfile — больше нет доступных дескрипторов файлов (для процесса операционной системы, в котором работает эмулятор Erlang)

• :enfile — таблица файлов переполнена (для всей операционной системы)

• :eacces — команда не указывает на исполняемый файл

• :enoent — команда не указывает на существующий файл

Команды оболочки

Если вы хотите выполнить доверенную команду внутри оболочки с каналами, перенаправлением и т. д., обратитесь к :os.cmd/1.

compiled_endianness()

Возвращает порядок байтов, с которым была скомпилирована система.

convert_time_unit(time, from_unit, to_unit)

convert_time_unit(integer(), time_unit() | :native, time_unit() | :native) :: integer()

Преобразует time из временной единицы from_unit во временную единицу to_unit.

Результат округляется с помощью функции floor.

convert_time_unit/3 принимает дополнительную временную единицу (кроме тех, что в типе time_unit/0), называемую :native. :native — это единица измерения времени, используемая системой выполнения Erlang. Она определяется при запуске системы выполнения и остаётся неизменной до её остановки. Чтобы определить, чему равна единица :native в системе, вы можете вызвать эту функцию для преобразования 1 секунды во временную единицу :native (т. е., System.convert_time_unit(1, :second, :native)).

cwd()

Текущий рабочий каталог.

Возвращает текущий рабочий каталог или nil при его отсутствии.

cwd!()

Текущий рабочий каталог, исключение при ошибке.

Возвращает текущий рабочий каталог или генерирует исключение RuntimeError.

delete_env(varname)

delete_env(String.t()) :: :ok

Удаляет переменную среды.

Удаляет переменную varname из среды.

endianness()

Возвращает порядок байтов.

find_executable(program)

find_executable(binary()) :: binary() | nil

Находит исполняемый файл в системе.

Эта функция ищет исполняемый файл по его имени, используя переменную среды PATH в Unix и Windows. Она также учитывает правильное расширение исполняемых файлов для каждой операционной системы, поэтому для Windows она будет искать файлы с расширениями .com, .cmd или подобными.

get_env()

get_env() :: %{optional(String.t()) => String.t()}

Переменные среды системы.

Возвращает список всех переменных среды. Каждая переменная представлена в виде кортежа {name, value}, где и имя name, и значение value являются строками.

get_env(varname)

get_env(binary()) :: binary() | nil

Значение переменной среды.

Возвращает значение переменной среды varname в виде бинарных данных или nil если переменная среды не определена.

get_pid()

get_pid() :: binary()

Идентификатор процесса виртуальной машины Erlang.

Возвращает идентификатор процесса текущего эмулятора Erlang в формате, обычно используемом средой операционной системы.

Для получения дополнительной информации см. :os.getpid/0.

halt(status \\ 0)

halt(non_neg_integer() | binary() | :abort) :: no_return()

Останавливает систему выполнения Erlang.

Останавливает систему выполнения Erlang, где аргумент status должен быть целым неотрицательным числом, атомом :abort или бинарными данными.

• Если целое число, система выполнения завершается с целочисленным значением, которое возвращается операционной системе.

• Если :abort, система выполнения прерывается, создавая дамп ядра, если это разрешено в операционной системе.

• Если строка, создаётся дамп памяти Erlang с статусом в качестве заголовка, а затем система выполнения завершается со статусом 1.

Обратите внимание, что во многих платформах операционная система поддерживает только коды состояния 0–255.

Для получения дополнительной информации см. :erlang.halt/1.

Примеры

System.halt(0)
System.halt(1)
System.halt(:abort)

monotonic_time()

monotonic_time() :: integer()

Возвращает текущее монотонное время в единицах :native.

Это время монотонно возрастает и начинается в неопределённый момент времени.

Встраивается компилятором в :erlang.monotonic_time/0.

monotonic_time(unit)

monotonic_time(time_unit()) :: integer()

Возвращает текущее монотонное время в указанной временной единице.

Это время монотонно возрастает и начинается в неопределённый момент времени.

os_time()

os_time() :: integer()

Возвращает текущее системное время.

Результат возвращается в единицах :native.

Это время может быть изменённо вперёд или назад без ограничений и не является монотонным.

Встраивается компилятором в :os.system_time/0.

os_time(unit)

os_time(time_unit()) :: integer()

Возвращает текущее системное время в указанной временной unit.

Это время может быть изменённо вперёд или назад без ограничений и не является монотонным.

otp_release()

otp_release() :: String.t()

Возвращает номер версии OTP.

put_env(enum)

put_env(Enumerable.t()) :: :ok

Устанавливает несколько переменных среды.

Устанавливает новое значение для каждой переменной среды, соответствующей каждому ключу в dict.

put_env(varname, value)

put_env(binary(), binary()) :: :ok

Устанавливает значение переменной среды.

Устанавливает новое value для переменной среды varname.

schedulers()

schedulers() :: pos_integer()

Возвращает количество планировщиков в виртуальной машине.

schedulers_online()

schedulers_online() :: pos_integer()

Возвращает количество активных планировщиков в виртуальной машине.

stacktrace()

Последний стек исключений.

Обратите внимание, что виртуальная машина Erlang (и, следовательно, эта функция) не возвращает текущий стек, а стек последнего возникшего исключения.

Встраивается компилятором в :erlang.get_stacktrace/0.

system_time()

system_time() :: integer()

Возвращает текущее системное время в единицах :native.

Это представление времени с точки зрения виртуальной машины os_time/0. Они могут не совпадать в случае искажений времени, хотя виртуальная машина стремится их синхронизировать. Это время не монотонно.

Встраивается компилятором в :erlang.system_time/0.

system_time(unit)

system_time(time_unit()) :: integer()

Возвращает текущее системное время в заданной единице измерения.

Это представление времени с точки зрения виртуальной машины (ВМ) os_time/0. Они могут не совпадать в случае временных сдвигов, хотя ВМ стремится к их выравниванию. Это время не является монотонным.

time_offset()

time_offset() :: integer()

Возвращает текущий временной сдвиг между монотонным временем ВМ Erlang и системным временем ВМ Erlang.

Результат возвращается в единицах времени :native.

Для получения дополнительной информации см. time_offset/1.

Встраивается в код компилятором в :erlang.time_offset/0.

time_offset(unit)

time_offset(time_unit()) :: integer()

Возвращает текущий временной сдвиг между монотонным временем ВМ Erlang и системным временем ВМ Erlang.

Результат возвращается в заданной единице измерения unit. Возвращаемый сдвиг, добавленный к монотонному времени Erlang (например, полученному с помощью monotonic_time/1), даёт системное время Erlang, соответствующее этому монотонному времени.

tmp_dir()

Директория временных файлов для записи.

Возвращает директорию временных файлов для записи. Ищет директории в следующем порядке:

1. Директорию, указанную переменной среды TMPDIR
2. Директорию, указанную переменной среды TEMP
3. Директорию, указанную переменной среды TMP
4. C:\TMP в Windows или /tmp в Unix
5. В крайнем случае, текущую рабочую директорию

Возвращает nil если ни одна из вышеперечисленных директорий не является доступной для записи.

tmp_dir!()

Директория временных файлов для записи с обработкой исключений.

Аналогично tmp_dir/0, но вместо возвращения nil, если директория временных файлов не задана, выбрасывает исключение RuntimeError.

unique_integer(modifiers \\ [])

unique_integer([:positive | :monotonic]) :: integer()

Генерирует и возвращает целое число, уникальное в текущей инстанции.

«Уникальность» означает, что эта функция, вызываемая с одним и тем же списком modifiers, никогда не вернёт одно и то же целое число более одного раза в текущей инстанции.

Если modifiers равно [], возвращается уникальное целое число (может быть положительным или отрицательным). Другие модификаторы могут быть переданы для изменения свойств возвращаемого целого числа:

• :positive - возвращаемое целое число гарантированно положительное.
• :monotonic - возвращаемое целое число возрастает монотонно. Это означает, что в одной и той же инстанции (но даже в разных процессах), целые числа, возвращаемые с помощью модификатора :monotonic, всегда будут строго меньше целых чисел, возвращаемых последующими вызовами с модификатором :monotonic.

Все вышеперечисленные модификаторы могут быть объединены; повторяющиеся модификаторы в modifiers будут проигнорированы.

Встраивается в код компилятором в :erlang.unique_integer/1.

user_home()

Директория пользователя.

Возвращает домашнюю директорию пользователя (платформонезависимо).

user_home!()

Домашняя директория пользователя с обработкой исключений.

Аналогично user_home/0, но вместо возвращения nil, если домашняя директория пользователя не задана, выбрасывает исключение RuntimeError.

version()

version() :: String.t()

Информация о версии Elixir.

Возвращает версию Elixir в виде бинарного значения.