Внедрение кода Julia

Примечание. В этом разделе приводятся сведения о внедрении кода Julia на C в операционных системах, подобных Unix. Сведения о выполнении этой задачи в ОС Windows см. в разделе Высокоуровневое внедрение в Windows с помощью Visual Studio.

Начнем с простой программы на C, которая инициализирует Julia и вызывает некоторый код Julia:

Чтобы создать эту программу, необходимо добавить путь к заголовку Julia в путь включаемых файлов и выполнить компоновку с libjulia. Например, если код Julia установлен в $JULIA_DIR, можно скомпилировать приведенную выше тестовую программу test.c с gcc, используя следующую строку:

Или же взглянем на программу embedding.c в дереве исходного кода Julia в папке test/embedding/. Файл программы cli/loader_exe.c представляет собой еще один простой пример задания параметров jl_options при компоновке с libjulia.

Первое, что необходимо сделать перед вызовом любой другой функции C в Julia, — инициализировать Julia. Для этого нужно вызвать метод jl_init, который пытается автоматически определить расположение установки Julia. Если необходимо указать пользовательское расположение или указать, какой образ системы следует загрузить, используйте jl_init_with_image.

Второй оператор в тестовой программе вычисляет оператор Julia с помощью вызова jl_eval_string.

Перед завершением программы настоятельно рекомендуется вызвать jl_atexit_hook. В приведенном выше примере команды вызов выполняется непосредственно перед возвратом из main.

Если переменная среды JULIA_DIR отсутствует, добавьте ее с помощью панели «Система» перед запуском Visual Studio. Папка bin в JULIA_DIR должна находиться в системной переменной PATH.

Начнем с открытия Visual Studio и создания проекта консольного приложения. Откройте файл заголовка stdafx.h и добавьте в его конец следующие строки:

Затем в проекте замените функцию main() следующим кодом:

Следующим шагом будет настройка проекта для поиска включаемых файлов и библиотек Julia. Важно знать версию установки Julia: 32- или 64-разрядная. Перед продолжением работы удалите все конфигурации платформы, которые не соответствуют установке Julia.

Используя диалоговое окно «Свойства» проекта, перейдите в раздел C/C++ | General и добавьте $(JULIA_DIR)\include\julia\ в свойство «Дополнительные каталоги включаемых файлов». Затем перейдите в раздел Linker | General и добавьте $(JULIA_DIR)\lib в свойство «Дополнительные каталоги включаемых файлов». Наконец, в разделе Linker | Input добавьте libjulia.dll.a;libopenlibm.dll.a; в список библиотек.

На этом этапе проект должен быть собран и запущен.

Реальные приложения должны будут не только выполнять выражения, но и возвращать их значения основной программе. jl_eval_string возвращает значение jl_value_t*, которое является указателем на выделяемый в куче объект Julia. Хранение таким способом простых типов данных типа Float64 называется boxing, а извлечение сохраненных примитивных данных — unboxing. Улучшенный пример программы, которая вычисляет квадратный корень из двух на Julia и возвращает результат на C, содержит в своем теле следующий код:

Чтобы проверить, относится ли ret к определенному типу Julia, можно использовать функции jl_isa, jl_typeis или jl_is_.... При вводе typeof(sqrt(2.0)) в оболочке Julia можно увидеть, что возвращаемым типом является Float64 (double в C). Для преобразования упакованного значения Julia в тип C double в приведенном выше фрагменте кода используется функция jl_unbox_float64.

Для обратного преобразования используются соответствующие функции jl_box_...:

Как мы увидим далее, для вызова функций Julia с определенными аргументами потребуется упаковка-преобразование.

Хотя скрипт jl_eval_string позволяет в C получить результат выражения Julia, он запрещает передавать аргументы, вычисленные на C, для Julia. Для этого потребуется вызывать функции Julia напрямую, используя jl_call:

На первом шаге дескриптор для функции Julia sqrt извлекается путем вызова jl_get_function. Первый аргумент, передаваемый функции jl_get_function, является указателем на модуль Base, в котором определена функция sqrt. Затем десятичное значение двойной точности упаковывается с помощью jl_box_float64. На последнем шаге функция вызывается с помощью jl_call1. Также существуют функции jl_call0, jl_call2 и jl_call3, позволяющие эффективно обрабатывать любое количество аргументов. Для передачи большого количества аргументов следует использовать функцию jl_call:

Ее второй аргумент, args, является массивом аргументов jl_value_t*, а nargs представляет количество аргументов.

Существует также альтернативный и, возможно, более простой способ вызова функций Julia — посредством @cfunction. Использование @cfunction позволяет осуществлять преобразование типов на стороне Julia, что обычно проще, чем на стороне C. Приведенный выше пример с функцией sqrt можно переписать с использованием @cfunction так:

Здесь мы сначала определяем вызываемую функцию C в Julia, затем извлекаем из нее указатель функции и, наконец, вызываем ее.

Как мы уже видели, объекты Julia представлены в языке C в виде указателей типа jl_value_t*. В связи с этим возникает вопрос о том, кто несет ответственность за освобождение этих объектов.

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

Сборщик мусора будет работать только при размещении новых объектов Julia в памяти. Выделение выполняется с помощью вызовов типа jl_box_float64, но оно может также произойти в любой момент выполнения кода Julia.

При написании кода с внедренными функциями Julia, как правило, безопасно будет использовать значения jl_value_t* между вызовами jl_... (так как сборщик мусора активируется только этими вызовами). Но чтобы значения гарантированно могли сохраняться после вызовов jl_..., необходимо сообщить Julia о наличии ссылки на значения Julia, требующие прав суперпользователя. Этот процесс называется предоставлением сборщику мусора прав суперпользователя. Получение прав суперпользователя для значения гарантирует, что сборщик мусора случайно не определит его как неиспользуемое и не освободит память, в которой оно хранится. Это можно сделать с помощью макроса JL_GC_PUSH:

Вызов JL_GC_POP освобождает ссылки, заданные предыдущим макросом JL_GC_PUSH. Обратите внимание, что макрос JL_GC_PUSH хранит ссылки в стеке C, поэтому он должен быть точно сопряжен с макросом JL_GC_POP перед выходом из области. То есть до того, как функция возвратит значение или поток управления покинет блок, в котором был вызван макрос JL_GC_PUSH.

С помощью макросов JL_GC_PUSH2--JL_GC_PUSH6 можно отправлять несколько значений Julia одновременно:

Чтобы отправить массив значений Julia, можно использовать макрос JL_GC_PUSHARGS следующим образом.

В каждой области должен быть только один вызов JL_GC_PUSH*, который должен быть сопоставлен только с одним вызовом JL_GC_POP. Если все необходимые переменные не могут быть отправлены одновременно с помощью одного вызова макроса JL_GC_PUSH* или необходимо отправить более шести переменных, а применение массива аргументов не является подходящим решением, можно использовать внутренние блоки:

Обратите внимание, что наличие действительных значений jl_value_t* перед вызовом JL_GC_PUSH* не является обязательным. Допустимо инициализировать часть переменных со значением NULL, передать их в JL_GC_PUSH*, а затем создать действительные значения Julia. Пример:

Если требуется сохранять указатель на переменную между функциями (или областями видимости блока), использовать макрос JL_GC_PUSH* нельзя. В этом случае необходимо создать и сохранить ссылку на переменную в глобальной области Julia. Одним из простых способов выполнения этой задачи является использование глобального типа IdDict, который будет хранить ссылки, запрещая сборщику мусора освобождать их. Однако этот метод будет работать правильно только с изменяемыми данными.

Если переменная неизменяема, ее необходимо заключить в эквивалентный изменяемый контейнер или, что предпочтительнее, в RefValue{Any} до ее отправки в IdDict. При таком подходе контейнер должен быть создан или заполнен с помощью кода C с использованием, например, функции jl_new_struct. Если контейнер создан с помощью jl_call*, необходимо перезагрузить указатель, который будет использоваться в коде C.

Чтобы разрешить сборщику мусора освобождать переменную, следует удалить ссылку на нее из refs с помощью функции delete! при условии, что никакая другая ссылка на переменную не хранится в каком-либо другом месте:

В качестве альтернативы для очень простых случаев можно просто создать глобальный контейнер типа Vector{Any} и извлекать из него элементы, когда это необходимо. Или даже можно создать одну глобальную переменную для каждого указателя, используя пример ниже.

Julia и C могут совместно использовать данные массивов без копирования. В следующем примере будет показано, как это работает.

Массивы Julia представлены в C типом данных jl_array_t*. По сути jl_array_t — это структура, которая содержит:

Для простоты начнем с одномерного массива. Создать массив, содержащий элементы Float64 длиной 10, можно следующим образом.

Или если вы уже выделили массив, можно создать тонкую оболочку вокруг его данных:

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

Чтобы получить доступ к данным x, можно использовать jl_array_data:

Теперь можно заполнить массив:

Вызовем функцию Julia, которая выполняет операцию с x на месте:

При выводе массива можно убедиться, что теперь элементы x расположены в обратном порядке.

Код Julia может вызывать исключения. Например, рассмотрим следующее.

Этот вызов, казалось бы, ничего не делает. Однако можно проверить, возникло ли исключение:

Если вы используете API Julia для C из языка, поддерживающего исключения (например, Python, C#, C++), имеет смысл заключить каждый вызов libjulia в функцию, которая проверяет, было ли вызвано исключение, а затем повторно создает исключение на основном языке.