@ccall library.function_name(argvalue1::argtype1, ...)::returntype
@ccall function_name(argvalue1::argtype1, ...)::returntype
@ccall $function_pointer(argvalue1::argtype1, ...)::returntype

Вызывает функцию в C-экспортированной динамической библиотеке, указанной library.function_name, где library — строковая константа или литерал. Библиотеку можно опустить, в этом случае function_name разрешается в текущем процессе. Кроме того, @ccall также может быть использовано для вызова указателя на функцию $function_pointer, например, возвращённой dlsym.

Каждый argvalue до @ccall преобразуется в соответствующий argtype, путём автоматического вставки вызовов unsafe_convert(argtype, cconvert(argtype, argvalue)). (См. также документацию по unsafe_convert и cconvert для получения дополнительных сведений.) В большинстве случаев это просто приводит к вызову convert(argtype, argvalue).

Примеры

@ccall strlen(s::Cstring)::Csize_t

Это вызывает функцию C стандартной библиотеки:

size_t strlen(char *)

с использованием переменной Julia с именем s. См. также ccall.

Поддержка аргументов переменной длины осуществляется по следующей схеме:

@ccall printf("%s = %d"::Cstring ; "foo"::Cstring, foo::Cint)::Cint

Точка с запятой используется для разделения обязательных аргументов (их должно быть как минимум один) от аргументов переменной длины.

Пример использования внешней библиотеки:

# C signature of g_uri_escape_string:
# char *g_uri_escape_string(const char *unescaped, const char *reserved_chars_allowed, gboolean allow_utf8);

const glib = "libglib-2.0"
@ccall glib.g_uri_escape_string(my_uri::Cstring, ":/"::Cstring, true::Cint)::Cstring

Строковый литерал также можно использовать непосредственно перед именем функции, если это необходимо "libglib-2.0".g_uri_escape_string(...

ccall((function_name, library), returntype, (argtype1, ...), argvalue1, ...)
ccall(function_name, returntype, (argtype1, ...), argvalue1, ...)
ccall(function_pointer, returntype, (argtype1, ...), argvalue1, ...)

Вызывает функцию в C-экспортированной динамической библиотеке, указанной кортежем (function_name, library), где каждый компонент — либо строка, либо символ. Вместо указания библиотеки можно также использовать символ или строку function_name, который разрешается в текущем процессе. Кроме того, ccall также может быть использовано для вызова указателя на функцию function_pointer, например, возвращенной dlsym.

Обратите внимание, что кортеж типа аргумента должен быть литеральным кортежем, а не кортежем-переменной или выражением.

Каждый argvalue до ccall будет преобразован в соответствующий argtype, путём автоматической вставки вызовов unsafe_convert(argtype, cconvert(argtype, argvalue)). (См. также документацию по unsafe_convert и cconvert для получения дополнительных сведений.) В большинстве случаев это просто приводит к вызову convert(argtype, argvalue).

cglobal((symbol, library) [, type=Cvoid])

Получает указатель на глобальную переменную в C-экспортированной динамической библиотеке, указанной точно так же, как в ccall. Возвращает Ptr{Type}, по умолчанию Ptr{Cvoid}, если аргумент Type не указан. Значения могут быть прочитаны или записаны с помощью unsafe_load или unsafe_store! соответственно.

@cfunction(callable, ReturnType, (ArgumentTypes...,)) -> Ptr{Cvoid}
@cfunction($callable, ReturnType, (ArgumentTypes...,)) -> CFunction

Генерирует указатель на C-вызываемую функцию из функции Julia callable для заданной подписи типа. Для передачи возвращаемого значения в ccall, используйте тип аргумента Ptr{Cvoid} в подписи.

Обратите внимание, что кортеж типа аргумента должен быть литеральным кортежем, а не кортежем-переменной или выражением (хотя он может включать оператор разброса). И что эти аргументы будут вычисляться в глобальной области видимости во время компиляции (а не откладываться до выполнения). Добавление '$' перед аргументом функции изменяет это, создавая замыкание во время выполнения над локальной переменной callable (это не поддерживается на всех архитектурах).

См. раздел руководства по использованию ccall и cfunction.

Примеры

julia> function foo(x::Int, y::Int)
           return x + y
       end

julia> @cfunction(foo, Int, (Int, Int))
Ptr{Cvoid} @0x000000001b82fcd0

CFunction struct

Дескриптор управления сборкой мусора для возвращаемого значения из @cfunction когда первый аргумент помечен '$'. Как и все cfunction дескрипторы, он должен быть передан в ccall как Ptr{Cvoid}, и будет автоматически преобразован в месте вызова в соответствующий тип.

См. @cfunction.

unsafe_convert(T, x)

Преобразует x в C-аргумент типа T где входной x должен быть результатом вызова cconvert(T, ...).

В случаях, когда convert потребовалось бы принять объект Julia и преобразовать его в Ptr, следует использовать эту функцию для определения и выполнения этого преобразования.

Следует позаботиться о том, чтобы ссылка Julia на x существовала до тех пор, пока результат этой функции будет использоваться. Соответственно, аргумент x этой функции никогда не должен быть выражением, только именем переменной или ссылкой на поле. Например, x=a.b.c допустимо, но x=[a,b,c] нет.

Префикс unsafe у этой функции указывает, что использование результата этой функции после того, как аргумент x этой функции больше не доступен программе, может привести к неопределенному поведению, включая повреждение программы или segfaults в любое последующее время.

См. также cconvert

cconvert(T,x)

Преобразует x в значение, которое должно быть передано в C-код как тип T, обычно вызывая convert(T, x).

В случаях, когда x нельзя безопасно преобразовать в T, в отличие от convert, cconvert может вернуть объект другого типа, но который подходит для обработки unsafe_convert. Результат этой функции следует хранить в корректном состоянии (для GC) до тех пор, пока результат unsafe_convert больше не требуется. Это можно использовать для выделения памяти, к которой будет обращаться ccall. Если необходимо выделить несколько объектов, в качестве возвращаемого значения можно использовать кортеж объектов.

Ни convert ни cconvert не должны принимать объект Julia и преобразовывать его в Ptr.

unsafe_load(p::Ptr{T}, i::Integer=1)
unsafe_load(p::Ptr{T}, order::Symbol)
unsafe_load(p::Ptr{T}, i::Integer, order::Symbol)

Загружает значение типа T из адреса i-го элемента (индексация с 1) начиная с p. Это эквивалентно C-выражению p[i-1]. При необходимости может быть указан порядок атомарной памяти.

Префикс unsafe у этой функции означает, что проверка указателя p на корректность не выполняется. Как и в C, программист отвечает за обеспечение того, чтобы ссылаемая память не освобождалась или не собиралась мусором во время вызова этой функции. Неправильное использование может привести к segfault вашей программы или возвращению ложных данных. В отличие от C, обращение к области памяти, выделенной как другой тип, может быть допустимо, при условии совместимости типов.

См. также: atomic

unsafe_store!(p::Ptr{T}, x, i::Integer=1)
unsafe_store!(p::Ptr{T}, x, order::Symbol)
unsafe_store!(p::Ptr{T}, x, i::Integer, order::Symbol)

Записывает значение типа T по адресу i-го элемента (индексация с 1) начиная с p. Это эквивалентно C-выражению p[i-1] = x. При необходимости может быть указан порядок атомарной памяти.

Префикс unsafe у этой функции означает, что проверка указателя p на корректность не выполняется. Как и в C, программист отвечает за обеспечение того, чтобы ссылаемая память не освобождалась или не собиралась мусором во время вызова этой функции. Неправильное использование может привести к segfault вашей программы. В отличие от C, запись в область памяти, выделенную как другой тип, может быть допустима при условии совместимости типов.

См. также: atomic

unsafe_modify!(p::Ptr{T}, op, x, [order::Symbol]) -> Pair

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

y = unsafe_load(p)
z = op(y, x)
unsafe_store!(p, z)
return y => z

Префикс unsafe у этой функции указывает, что никакая валидация не выполняется для указателя p, чтобы убедиться, что он действителен. Как и в C, программист несет ответственность за обеспечение того, чтобы ссылаемая память не освобождалась и не собиралась мусором во время вызова этой функции. Неправильное использование может привести к ошибке сегментации вашей программы.

См. также: modifyproperty!, atomic

unsafe_replace!(p::Ptr{T}, expected, desired,
               [success_order::Symbol[, fail_order::Symbol=success_order]]) -> (; old, success::Bool)

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

y = unsafe_load(p, fail_order)
ok = y === expected
if ok
    unsafe_store!(p, desired, success_order)
end
return (; old = y, success = ok)

Префикс unsafe у этой функции указывает, что никакая валидация не выполняется для указателя p, чтобы убедиться, что он действителен. Как и в C, программист несет ответственность за обеспечение того, чтобы ссылаемая память не освобождалась и не собиралась мусором во время вызова этой функции. Неправильное использование может привести к ошибке сегментации вашей программы.

См. также: replaceproperty!, atomic

unsafe_swap!(p::Ptr{T}, x, [order::Symbol])

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

y = unsafe_load(p)
unsafe_store!(p, x)
return y

Префикс unsafe у этой функции указывает, что никакая валидация не выполняется для указателя p, чтобы убедиться, что он действителен. Как и в C, программист несет ответственность за обеспечение того, чтобы ссылаемая память не освобождалась и не собиралась мусором во время вызова этой функции. Неправильное использование может привести к ошибке сегментации вашей программы.

См. также: swapproperty!, atomic

unsafe_copyto!(dest::Ptr{T}, src::Ptr{T}, N)

Копирует N элементы из указателя-источника в указатель-приемник без проверок. Размер элемента определяется типом указателей.

Префикс unsafe у этой функции указывает, что никакая валидация не выполняется для указателей dest и src для проверки их корректности. Неправильное использование может привести к повреждению или ошибке сегментации вашей программы, так же как и в C.

unsafe_copyto!(dest::Array, do, src::Array, so, N)

Копирует N элементы из исходного массива в целевой массив, начиная с линейного индекса so в исходном и do в целевом (индексация с 1).

Префикс unsafe у этой функции указывает, что не выполняется проверка, чтобы убедиться, что N находится в границах массива. Неправильное использование может привести к повреждению или ошибке сегментации вашей программы, так же как и в C.

copyto!(B::AbstractMatrix, ir_dest::AbstractUnitRange, jr_dest::AbstractUnitRange,
        tM::AbstractChar,
        M::AbstractVecOrMat, ir_src::AbstractUnitRange, jr_src::AbstractUnitRange) -> B

Эффективно копирует элементы матрицы M в B в зависимости от параметра символа tM следующим образом:

Элементы B[ir_dest, jr_dest] перезаписываются. Кроме того, параметры диапазона индексов должны удовлетворять условиям length(ir_dest) == length(ir_src) и length(jr_dest) == length(jr_src).

См. также copy_transpose! и copy_adjoint!.

copyto!(dest::AbstractMatrix, src::UniformScaling)

Копирует UniformScaling на матрицу.

copyto!(dest, do, src, so, N)

Копирует N элементы из коллекции src, начиная с линейного индекса so, в массив dest, начиная с индекса do. Возвращает dest.

copyto!(dest::AbstractArray, src) -> dest

Копирует все элементы из коллекции src в массив dest, длина которого должна быть больше или равна длине n коллекции src. Первые n элементов dest перезаписываются, остальные остаются без изменений.

См. также copy!, copy.

Примеры

julia> x = [1., 0., 3., 0., 5.];

julia> y = zeros(7);

julia> copyto!(y, x);

julia> y
7-element Vector{Float64}:
 1.0
 0.0
 3.0
 0.0
 5.0
 0.0
 0.0

copyto!(dest, Rdest::CartesianIndices, src, Rsrc::CartesianIndices) -> dest

Копирует блок src в диапазоне Rsrc в блок dest в диапазоне Rdest. Размеры двух областей должны совпадать.

Примеры

julia> A = zeros(5, 5);

julia> B = [1 2; 3 4];

julia> Ainds = CartesianIndices((2:3, 2:3));

julia> Binds = CartesianIndices(B);

julia> copyto!(A, Ainds, B, Binds)
5×5 Matrix{Float64}:
 0.0  0.0  0.0  0.0  0.0
 0.0  1.0  2.0  0.0  0.0
 0.0  3.0  4.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0

pointer(array [, index])

Получить базовый адрес массива или строки, необязательно в заданном месте index.

Эта функция «небезопасная». Будьте внимательны, чтобы убедиться, что ссылка Julia на array существует, пока этот указатель будет использоваться. Макрос GC.@preserve должен использоваться для защиты аргумента array от сбора мусора в данном блоке кода.

Вызов Ref(array[, index]) обычно предпочтительнее этой функции, так как он гарантирует действительность.

unsafe_wrap(Array, pointer::Ptr{T}, dims; own = false)

Оборачивает объект Julia Array вокруг данных по адресу, заданному pointer, без копирования. Тип элемента указателя T определяет тип элемента массива. dims это либо целое число (для одномерного массива), либо кортеж из размерностей массива. own необязательно указывает, должен ли Julia принять на себя владение памятью, вызывая free для указателя, когда массив больше не используется.

Эта функция помечена как «небезопасная», потому что она вызовет ошибку, если pointer не является допустимым адресом памяти для данных нужной длины. В отличие от unsafe_load и unsafe_store!, программист также несет ответственность за обеспечение того, что к данным не обращаются через два массива с разными типами элементов, аналогично правилу строгого алиасинга в C.

pointer_from_objref(x)

Получите адрес памяти объекта Julia в виде Ptr. Существование полученного Ptr не защитит объект от сборки мусора, поэтому необходимо убедиться, что объект ссылается в течение всего времени, пока Ptr будет использоваться.

Данная функция не может быть вызвана для неизменяемых объектов, так как у них нет стабильных адресов памяти.

См. также unsafe_pointer_to_objref.

unsafe_pointer_to_objref(p::Ptr)

Преобразуйте Ptr в ссылку на объект. Предполагается, что указатель ссылается на действительный объект Julia, выделенный в куче. Если это не так, результат неопределён, поэтому данная функция считается «небезопасной» и должна использоваться с осторожностью.

См. также pointer_from_objref.

disable_sigint(f::Function)

Отключить обработчик Ctrl+C во время выполнения функции на текущей задаче для вызова внешнего кода, который может вызывать код Julia, который не является безопасным для прерывания. Предполагается, что вызов осуществляется с помощью синтаксиса блока do, как показано ниже:

disable_sigint() do
    # interrupt-unsafe code
    ...
end

Это не требуется для рабочих потоков (Threads.threadid() != 1), так как InterruptException будет доставлен только на главный поток. Внешние функции, которые не вызывают код Julia или запуск Julia, автоматически отключают sigint во время выполнения.

reenable_sigint(f::Function)

Включить обработчик Ctrl+C во время выполнения функции. Временный откат действия disable_sigint.

exit_on_sigint(on::Bool)

Установить флаг exit_on_sigint среды выполнения Julia. Если false, Ctrl+C (SIGINT) можно перехватить как InterruptException в блоке try. Это стандартное поведение в REPL, любом коде, запущенном через -e и -E, и в скриптах Julia, запущенных с параметром -i.

Если true, InterruptException не генерируется при нажатии Ctrl+C. Для выполнения кода при таком событии требуется atexit. Это стандартное поведение в скриптах Julia, запущенных без параметра -i.

systemerror(sysfunc[, errno::Cint=Libc.errno()])
systemerror(sysfunc, iftrue::Bool)

Возбуждает SystemError для errno с описательной строкой sysfunc, если iftrue равно true

windowserror(sysfunc[, code::UInt32=Libc.GetLastError()])
windowserror(sysfunc, iftrue::Bool)

Аналогично systemerror, но для функций API Windows, которые используют GetLastError для возвращения кода ошибки вместо установки errno.

Ptr{T}

Адрес памяти, указывающий на данные типа T. Однако нет гарантии, что память действительна или что она действительно представляет данные указанного типа.

Ref{T}

Объект, который безопасно ссылается на данные типа T. Этот тип гарантирует, что он указывает на действительную память, выделенную Julia, правильного типа. Данные защищены от освобождения сборщиком мусора, пока на сам Ref есть ссылка.

В Julia объекты Ref обращаются (загружаются или сохраняются) с помощью [].

Создание Ref к значению x типа T обычно записывается как Ref(x). Дополнительно, для создания внутренних указателей на контейнеры (такие как Array или Ptr) можно записать Ref(a, i), чтобы создать ссылку на i-й элемент a.

Ref{T}() создает ссылку на значение типа T без инициализации. Для T, значением будет то, что в данный момент находится в выделенной памяти. Для T, ссылка будет неопределённой, и попытка обращение к ней приведёт к ошибке "UndefRefError: доступ к неопределённой ссылке".

Для проверки того, является ли Ref неопределённой ссылкой, используйте isassigned(ref::RefValue). Например, isassigned(Ref{T}()) равно false, если T не является типом bitstype. Если T это bitstype, isassigned(Ref{T}()) всегда будет истинным.

При передаче в качестве аргумента ccall (как Ptr или Ref типа), объект Ref будет преобразован в родной указатель на данные, на которые он ссылается. Для большинства T, или при преобразовании в Ptr{Cvoid}, это указатель на данные объекта. Когда T это тип isbits, это значение можно безопасно изменять, в противном случае изменение строго неопределённо.

В качестве особого случая, установка T = Any вместо этого вызовет создание указателя на саму ссылку при преобразовании в Ptr{Any} (jl_value_t const* const*, если T неизменяем, иначе jl_value_t *const *). При преобразовании в Ptr{Cvoid}, он по-прежнему вернёт указатель на область данных, как и в любом другом T.

Экземпляр C_NULL типа Ptr можно передать в аргумент ccall Ref для его инициализации.

Использование в распараллеливании

Ref иногда используется в распараллеливании для обработки ссылаемых значений как скаляров.

Примеры

julia> r = Ref(5) # Create a Ref with an initial value
Base.RefValue{Int64}(5)

julia> r[] # Getting a value from a Ref
5

julia> r[] = 7 # Storing a new value in a Ref
7

julia> r # The Ref now contains 7
Base.RefValue{Int64}(7)

julia> isa.(Ref([1,2,3]), [Array, Dict, Int]) # Treat reference values as scalar during broadcasting
3-element BitVector:
 1
 0
 0

julia> Ref{Function}()  # Undefined reference to a non-bitstype, Function
Base.RefValue{Function}(#undef)

julia> try
           Ref{Function}()[] # Dereferencing an undefined reference will result in an error
       catch e
           println(e)
       end
UndefRefError()

julia> Ref{Int64}()[]; # A reference to a bitstype refers to an undetermined value if not given

julia> isassigned(Ref{Int64}()) # A reference to a bitstype is always assigned
true

isassigned(ref::RefValue) -> Bool

Проверка, связан ли данный Ref со значением. Это всегда верно для Ref объекта bitstype. Вернуть false, если ссылка неопределённа.

Примеры

julia> ref = Ref{Function}()
Base.RefValue{Function}(#undef)

julia> isassigned(ref)
false

julia> ref[] = (foobar(x) = x)
foobar (generic function with 1 method)

julia> isassigned(ref)
true

julia> isassigned(Ref{Int}())
true

Cchar

Эквивалент родному char типу С.

Cuchar

Эквивалент родному unsigned char типу С (UInt8).

Cshort

Эквивалент родному signed short типу С (Int16).

Cstring

Строка в стиле С, состоящая из символов родного типа Cchar. Строки в стиле С завершаются нулём. Для строк в стиле С, составленных из родного типа широких символов, см. Cwstring. Дополнительную информацию о взаимодействии строк с С см. в руководстве.

Cushort

Эквивалент родному unsigned short типу С (UInt16).

Cint

Эквивалент встроенному типу signed int c (Int32).

Cuint

Эквивалент встроенному типу unsigned int c (UInt32).

Clong

Эквивалент встроенному типу signed long c-типа.

Culong

Эквивалент встроенному типу unsigned long c-типа.

Clonglong

Эквивалент встроенному типу signed long long c-типа (Int64).

Culonglong

Эквивалент встроенному типу unsigned long long c-типа (UInt64).

Cintmax_t

Эквивалент встроенному типу intmax_t c-типа (Int64).

Cuintmax_t

Эквивалент встроенному типу uintmax_t c-типа (UInt64).

Csize_t

Эквивалент встроенному типу size_t c-типа (UInt).

Cssize_t

Эквивалент встроенному типу ssize_t c-типа.

Cptrdiff_t

Эквивалент встроенному типу ptrdiff_t c-типа (Int).

Cwchar_t

Эквивалент встроенному типу wchar_t c-типа (Int32).

Cwstring

Строка в стиле C, составленная из нативных символов типа Cwchar_t. Такие строки завершаются символом NUL. Для строк в стиле C, составленных из нативного типа символов, см. Cstring. Дополнительную информацию о взаимодействии строк с C см. в справочнике.

Cfloat

Эквивалент встроенному типу float c-типа (Float32).

Cdouble

Эквивалент встроенному типу double c-типа (Float64).

llvmcall(fun_ir::String, returntype, Tuple{argtype1, ...}, argvalue1, ...)
llvmcall((mod_ir::String, entry_fn::String), returntype, Tuple{argtype1, ...}, argvalue1, ...)
llvmcall((mod_bc::Vector{UInt8}, entry_fn::String), returntype, Tuple{argtype1, ...}, argvalue1, ...)

Вызов кода LLVM, переданного в первом аргументе. Есть несколько способов указать этот первый аргумент:

• в виде литеральной строки, представляющей IR уровня функции (аналогично блоку LLVM define), где аргументы доступны как последовательные неуказанные переменные SSA (%0, %1 и т.д.);
• в виде кортежа из 2 элементов: строки модуля IR и строки, представляющей имя функции точки входа для вызова;
• в виде кортежа из 2 элементов, но с модулем, предоставленным как Vector{UInt8} с биткодом.

Обратите внимание, что в отличие от ccall, типы аргументов необходимо указывать как кортеж типа, а не кортеж типов. Все типы, а также код LLVM должны быть указаны как литералы, а не как переменные или выражения (возможно, потребуется использовать @eval для создания этих литералов).

Не допускаются указатели на непрозрачные данные (записанные как ptr) в коде LLVM.

Примеры использования см. в test/llvmcall.jl.