Система

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

Время

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

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

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

Если во время выполнения кода системные часы изменяются, некоторый код, выполнявшийся в течение 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(): Последний стек исключений
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 нормализует их написание для соответствия соглашению SI.

Функции

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 - устанавливает аргумент command 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 со значением status в качестве слогана, а затем система выполнения завершается со статусом 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

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

Устанавливает новое значение для каждой переменной окружения, соответствующей каждой паре {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()

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

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

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

stop(status \\ 0)

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

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

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

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

Для получения дополнительной информации см. :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()

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

Результат возвращается в заданных единицах времени 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 в виде бинарного значения.