@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} в подписи.

Обратите внимание, что кортеж типов аргументов должен быть литеральным кортежем, а не переменной или выражением, содержащим кортеж (хотя он может содержать оператор splat). И эти аргументы будут вычислены в глобальной области видимости во время компиляции (а не отложены до выполнения). Добавление '$' перед аргументом функции изменяет это, создавая замыкание во время выполнения над локальной переменной 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 может вернуть объект типа, отличного от T, который, тем не менее, подходит для unsafe_convert для обработки. Результат этой функции должен оставаться валидным (для GC) до тех пор, пока результат unsafe_convert больше не нужен. Это может быть использовано для выделения памяти, к которой будет обращаться ccall. Если нужно выделить несколько объектов, в качестве значения возврата можно использовать кортеж из объектов.

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

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

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

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

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

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

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

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

Копирование N элементов из исходного указателя в целевой, без проверок. Размер элемента определяется типом указателей.

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

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

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

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

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

Копирует блок данных в диапазоне Rsrc в блок данных в диапазоне 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

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

Копирует единичную матрицу UniformScaling в матрицу-приемник.

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 runtime, автоматически отключают обработчик sigint во время своего выполнения.

reenable_sigint(f::Function)

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

exit_on_sigint(on::Bool)

Устанавливает флаг exit_on_sigint Julia runtime. Если 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 не является битовым типом. Если 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 может быть передан аргументу ccall Ref для его инициализации.

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

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

Примеры

julia> Ref(5)
Base.RefValue{Int64}(5)

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

julia> Ref{Int64}(0)[] == 0 # Explicitly give a value for a bitstype reference
true

isassigned(ref::RefValue) -> Bool

Проверка, связан ли данный Ref со значением. Это всегда истинно для Ref объекта битового типа. Возвращает 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

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

Cshort

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

Cstring

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

Cushort

Эквивалентно нативному типу unsigned short c (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. Строки в стиле C завершаются символом 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 для генерации этих литералов).

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