Система

Модуль 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): Возвращает текущее время ОС в заданной единице измерения
otp_release(): Возвращает номер версии OTP
put_env(enum): Устанавливает несколько переменных окружения
put_env(varname, value): Устанавливает значение переменной окружения
schedulers(): Возвращает количество планировщиков в ВМ
schedulers_online(): Возвращает количество работающих планировщиков в ВМ
stacktrace(): Последний стек исключений
stop(status \\ 0): Осторожно завершает систему выполнения Erlang
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()) :: {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()}

Возвращает все переменные среды системы.

Возвращаемое значение — это карта, содержащая пары имя-значение. Имена переменных и их значения — это строки.

get_env(varname)

get_env(String.t()) :: String.t() | 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 без надлежащего завершения работы приложений и портов. См. stop/1 для аккуратного завершения работы системы.

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.

stop(status \\ 0)

stop(non_neg_integer() | binary()) :: no_return()

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

Все приложения останавливаются плавно, весь код разгружается, и все порты закрываются перед завершением работы системы вызовом halt/1.

status должно быть целое неотрицательное значение, возвращаемое системой выполнения операционной системе.

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

Дополнительную информацию можно найти в :init.stop/1.

Примеры

System.stop(0)
System.stop(1)

system_time()

system_time() :: integer()

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

Это представление ВМ времени os_time/0. Они могут не совпадать в случае сбросов времени, хотя ВМ стремится их выровнять. Это время не монотонно.

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

system_time(unit)

system_time(time_unit()) :: integer()

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

time_offset()

time_offset() :: integer()

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

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

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

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

time_offset(unit)

time_offset(time_unit()) :: integer()

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

tmp_dir()

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

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

директория, указанная переменной окружения TMPDIR
директория, указанная переменной окружения TEMP
директория, указанная переменной окружения TMP
C:\TMP в Windows или /tmp в Unix
в крайнем случае, текущая рабочая директория

Возвращает 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 в виде двоичного значения.