@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.

Поддерживаются аргументы с переменным числом параметров (varargs) с использованием следующей конвенции:

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

reenable_sigint(f::Function)

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

exit_on_sigint(on::Bool)

Установить флаг exit_on_sigint runtime 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, значение будет таким, какое в данный момент находится в выделенной памяти. Для не-bitstype 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> 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 объекта 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

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

Cshort

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

Cstring

Строка в стиле C, состоящая из символов родного типа Cchar. Строки Cstring завершаются символом NUL. Для строк в стиле 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 завершаются нулём. Для строк в стиле 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 и т.д.);
• в виде пары из двух строк, содержащей IR-код модуля и имя вызываемой функции входа;
• в виде пары из двух элементов, но с модулем, представленным как Vector{UInt8} с биткодом.

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

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