@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 для этой функции больше не доступен программе, может привести к неопределенному поведению, включая повреждение программы или сегментацию, в любое более позднее время.

См. также cconvert

cconvert(T,x)

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

В случаях, когда x не может быть безопасно преобразован в T, в отличие от convert, cconvert может вернуть объект типа, отличного от T, который, тем не менее, подходит для обработки с помощью unsafe_convert. Результат этой функции должен оставаться действительным (для сборщика мусора) до тех пор, пока результат 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, программист несет ответственность за то, чтобы ссылка на память не была освобождена или собрана сборщиком мусора во время вызова этой функции. Неправильное использование может привести к сбою вашей программы или возврату мусорных значений. В отличие от 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, программист несет ответственность за то, чтобы ссылка на память не была освобождена или собрана сборщиком мусора во время вызова этой функции. Неправильное использование может привести к сбою вашей программы. В отличие от 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)

Оборачивает объект Array в Julia вокруг данных по адресу, указанному в 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
    # код, небезопасный для прерывания
    ...
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, но для функций Windows API, которые используют 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 не является типом битов. Если T является типом битов, 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 может быть передан в аргумент Ref ccall, чтобы инициализировать его.

Использование в широковещательной передаче

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

Примеры

julia> r = Ref(5) # Создать Ref с начальным значением
Base.RefValue{Int64}(5)

julia> r[] # Получение значения из Ref
5

julia> r[] = 7 # Сохранение нового значения в Ref
7

julia> r # Ref теперь содержит 7
Base.RefValue{Int64}(7)

julia> isa.(Ref([1,2,3]), [Array, Dict, Int]) # Рассматривать ссылочные значения как скалярные во время широковещательной передачи
3-element BitVector:
 1
 0
 0

julia> Ref{Function}()  # Неопределенная ссылка на не битовый тип, Function
Base.RefValue{Function}(#undef)

julia> try
           Ref{Function}()[] # Разыменование неопределенной ссылки приведет к ошибке
       catch e
           println(e)
       end
UndefRefError()

julia> Ref{Int64}()[]; # Ссылка на битовый тип ссылается на неопределенное значение, если не задана

julia> isassigned(Ref{Int64}()) # Ссылка на битовый тип всегда назначена
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 в C.

Cuchar

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

Cshort

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

Cstring

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

Cushort

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

Cint

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

Cuint

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

Clong

Эквивалентно родному типу signed long в C.

Culong

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

Clonglong

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

Culonglong

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

Cintmax_t

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

Cuintmax_t

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

Csize_t

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

Cssize_t

Эквивалентно нативному типу ssize_t на C.

Cptrdiff_t

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

Cwchar_t

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

Cwstring

C-строка, состоящая из нативного типа широких символов Cwchar_t. Cwstring заканчивается на 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 на уровне функции (аналогично блоку define в LLVM), где аргументы доступны как последовательные неназванные переменные SSA (%0, %1 и т.д.);
• в виде кортежа из 2 элементов, содержащего строку модуля IR и строку, представляющую имя функции точки входа для вызова;
• в виде кортежа из 2 элементов, но с модулем, предоставленным как Vector{UInt8} с биткодом.

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

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

Смотрите test/llvmcall.jl для примеров использования.