Система

Модуль 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(): Возвращает номер версии Erlang/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!()

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

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

cwd()

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

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

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.

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

Встроенная компилятором.

monotonic_time(unit)

monotonic_time(time_unit()) :: integer()

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

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

os_time()

os_time() :: integer()

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

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

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

Встроенная компилятором.

os_time(unit)

os_time(time_unit()) :: integer()

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

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

otp_release()

otp_release() :: String.t()

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

put_env(enum)

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

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

Устанавливает новое значение для каждой переменной окружения, соответствующей каждой паре {key, value} в enum.

put_env(varname, value)

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

Устанавливает значение переменной окружения.

Устанавливает новое значение value для переменной окружения varname.

schedulers()

schedulers() :: pos_integer()

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

schedulers_online()

schedulers_online() :: pos_integer()

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

stacktrace()

Устаревший механизм получения последнего трассировки стека исключений.

Доступ к трассировке стека вне блока rescue/catch устарел. Если вы хотите поддерживать только Elixir v1.7+, вы должны обращаться к __STACKTRACE__/0 внутри блока rescue/catch. Если вы хотите поддерживать более ранние версии Elixir, переместите System.stacktrace/0 в блок rescue/catch.

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

stop(status \\ 0) (since 1.5.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). Они могут не совпадать в случае временных искажений, хотя виртуальная машина стремится их согласовать. Это время не монотонно.

Встраивается компилятором.

system_time(unit)

system_time(time_unit()) :: integer()

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

time_offset()

time_offset() :: integer()

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

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

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

Встраивается компилятором.

time_offset(unit)

time_offset(time_unit()) :: integer()

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

tmp_dir!()

Записываемый временный каталог, исключение при ошибке.

То же, что и tmp_dir/0, но поднимает RuntimeError вместо возвращения nil если временный каталог не установлен.

tmp_dir()

Записываемый временный каталог.

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

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

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

unique_integer(modifiers \\ [])

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

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

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

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

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

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

Встраивается компилятором.

user_home!()

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

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

user_home()

Домашний каталог пользователя.

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

version()

version() :: String.t()

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

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