Система

Модуль 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 для преобразования в определённые единицы, такие как миллисекунды или микросекунды. Более подробную информацию см. в типе 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(): Последний стек исключений
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 ::
  :seconds |
  :milliseconds |
  :microseconds |
  :nanoseconds |
  pos_integer

Единицы измерения времени, передаваемые функциям, таким как monotonic_time/1, и другим.

Единицы измерения времени :seconds, :milliseconds, :microseconds и :nanoseconds управляют значениями возвращаемыми функциями, принимающими единицы измерения времени.

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

Обратите внимание, что API Erlang использует :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 не используется явно)
аргументы не нужно экранировать или заключать в кавычки для безопасности оболочки

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

Примеры

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), называемую :native. :native — это временная единица, используемая системой выполнения Erlang. Она определяется при запуске системы выполнения и остается неизменной до ее остановки. Чтобы определить, чему соответствует единица :native в системе, вы можете вызвать эту функцию для преобразования 1 секунды во временную единицу :native (т. е., System.convert_time_unit(1, :seconds, :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

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

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, но генерирует исключение RuntimeError вместо возвращения nil если временная директория не задана.

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, но генерирует исключение RuntimeError вместо возвращения nil если домашняя директория пользователя не задана.

version()

version() :: String.t

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

Возвращает информацию о версии Elixir в виде бинарного представления.