jluna: A Julia Wrapper for C++

Welcome to the documentation for jluna, a Julia-wrapper for C++.

It allows for easy integration of Julia scripts and packages into projects with C++ as the host language, making language interaction easy and convenient.

It is available under MIT License, on GitHub.

This documentation includes a step-by-step guide on how to install jluna, a manual and tutorial introducing all of jlunas features, as well as an index of all of jlunas function, intended to be easily referenced back to during development.

jluna was designed and implemented by C. Cords.

---

Note

For all chapters, an interactive list of sections is provided in the top right corner of the page.

Table of Contents

Please navigate to the appropriate section below:

• Installation
  • Installing jluna
    • Cloning from Git
    • Configure CMake
    • Make Install & Test
    • Linking
    • Example: Hello World
• Troubleshooting
  • Permission Denied
  • Unable to detect the Julia executable
  • Found unsuitable version
  • Could NOT find Julia (missing: X)
  • Cannot find <julia.h> / <jluna.hpp>
  • Cannot find libjluna
  • error: concept does not name a type
  • Segmentation fault in expression starting at none:0
  • Warning: copy relocation against non-copyable protected symbol
• Basics
  • Initializing the Julia State
  • Executing Julia Code
    • Executing a Single Line of Code
    • Executing a File
    • Executing Multiple Lines of Code
  • Getting the Result of Julia Code
  • Executing Julia Code in Module Scope
  • Calling Julia Functions
    • Accessing Named Variables in a Module
  • Accessing Julia Struct Fields
  • Mutating Julia-side Variables
  • Mutating Variables using operator[](size_t)
• Proxies
  • Shared & Separate Memory
  • Constructing a Proxy
  • Changing a Proxies Value
  • Boxing & Unboxing
    • Boxing
    • Unboxing
  • (Un)Boxable Types
  • Named & Unnamed Proxies
    • Unnamed Proxies
  • Named Proxy
  • Proxy: Additional Member Functions
  • Detached Proxies
  • Making a Named Proxy Unnamed
  • Implications
  • Proxy Inheritance
• Specialized Proxies: Arrays
  • Accessing Array Indices
    • Linear Indexing
    • List Indexing
    • 0-base vs. 1-base
    • Iterating
    • Accessing the Size of an Array
    • jluna::Vector
  • Generator Expressions
• Specialized Proxies: Symbols
  • Symbol Hashing
• Specialized Proxies: Modules
  • Assign in Module
  • Creating a new Variable
  • Import, Using, Include
• Calling C++ Functions from Julia
  • Creating a Function Object
  • Allowed Signatures
  • Taking Any Number of Arguments
  • Using Non-Julia Objects
• Specialized Proxies: Types
  • Constructing a Type
  • Base Types
  • Type Order
  • Type Info
  • Parameters
  • Fields
  • Type Classification
  • “Unrolling” Types
• Usertypes
  • Usertype Interface
  • Step 1: Making the Type Compliant
  • Step 2: Enabling the Interface
  • Step 3: Adding Property Routines
  • Step 4: Implementing the Type
  • Step 5: Usage
  • Example Summary
  • Usertype: Additional Member Functions
• Multi Threading
  • Initializing the Julia Threadpool
  • Creating a Task
  • Running a Task
  • Managing a Tasks Lifetime
  • Accessing a Tasks State
  • Accessing a Tasks Result
  • Data Race Freedom
  • Thread-Safety
  • Thread-Safety in Julia
  • Thread-Safety in C++
  • Multi-Threading: Closing Notes
    • Interacting with jluna::Task from Julia
    • Moving / Copying Tasks
    • Do NOT use @threadcall
• The unsafe Library
  • Unsafe Types
  • Acquiring Raw Pointers
    • From Proxies
    • From Julia-side Values
  • Calling Julia Functions
  • Executing Strings as Code
  • Boxing / Unboxing
  • Protecting Values from the Garbage Collector
    • Disabling the GC
  • Accessing & Mutating a Variable
  • unsafe Array Interface
  • Accessing an Array Element
  • Allocating a New Array
    • Creating a Thin Wrapper Around Already Existing Data
  • Resizing an Array
    • Replacing an Arrays Data
  • Shared Memory
• Performance Optimization
  • Methodology
  • Results: Introduction
  • Benchmark: Accessing Julia-side Values
  • Accessing Julia-side Values: Results
  • Benchmark: Mutating Julia-side Variables
  • Mutating Julia-side Variables: Results
  • Benchmark: Calling Julia-side Functions
  • Calling Julia-side Functions: Results
  • Benchmark: Calling C++ Functions from Julia
  • Calling C++ Functions from Julia: Results
  • Benchmark: Using jluna::Array
  • Using jluna::Array: Results
  • Benchmark: Constructing jluna::Task
  • Constructing jluna::Task: Results
  • Performance Evaluation: Summary
    • Accessing Julia Values
    • Changing a Julia Value
    • Creating a Julia Variable
    • Calling a Julia Function
    • Executing Strings as Julia Code
    • Handling Big Arrays
    • Multi-Threading
• Closing Statement
• Library Index
  • Box
    • Concept: is_boxable
  • Unbox
    • Concept: is_unboxable
  • Safe
    • Safe: Initialize
    • Safe: Call Function
    • Safe: Eval
    • Safe: Miscellaneous
  • Unsafe
    • GC
    • Unsafe: Get / Call Functions
    • Unsafe: Get / Set Values
    • Unsafe: Get / Set Fields
    • Unsafe: Expressions
  • Proxy
  • Module
    • Unsafe: Arrays
  • Array
    • Array: Non-Const Iterator
    • Array: Const Iterator
    • Array: Typedefs
    • Vector
  • cppcall
  • Exceptions
  • Generator Expression
  • Multi Threading
    • Future
    • Task
    • ThreadPool
    • Mutex
  • Symbol
  • Type
  • Typedefs
  • Usertype

---

FAQ: What is the difference between jluna and …?

With C++ being as widely used as it is, confusion may arise as to what purpose jluna serves when compared to a number of other C++-interfacing Julia packages. These will be addressed in this section.

Julia C-API

The Julia C-API provides the “backbone” of Julia and is the basis for jluna and most other foreign-language libraries interacting with Julia. While powerful, the C-API can be quite hard to use and poorly documented. jluna aims to resolve this, fully wrapping the C-API in all of the convenience of modern C++: automatic memory management, proper exception handling and much nicer syntax. Other than this, Julia C-API and jluna are functionally equivalent.

The one area where jluna actually has more features than the C-API is in parallelization: jluna provides a thread pool that allows C-side functions to interact with the Julia state, something that is not possible using only he C-API.

Cxx.jl

Cxx.jl aims to provide users with a way to run C++ code natively from within Julia, using the @cxx macro. Unlike jluna, Cxx.jl assumes Julia as the host language, while jluna assumes C++. Furthermore, the Cxx.jl is currently unmaintained, only supporting Julia versions older than 1.3. jluna specifically requires 1.7 or newer.

CxxWrap.jl

CxxWrap.jl is related to Cxx.jl, in that both assume Julia as the host language and both allow for direct access of C++ functionality from within Julia. It allows to compile C++ code into a shared library that can then be used directly from within Julia. This is very similar to jluna, with two major difference: Firstly, jluna is a Julia-wrapper for C++, while CxxWrap is a C++-wrapper for Julia. While, in concept, both overlap, the decision on which to use should be based on what host language a specific project has. If Julia is the “main” language that interacts with all parts of a project, CxxWrap.jl may be a better fit than jluna, if C++ takes that place, jluna may be superior.

In addition, CxxWrap.jl and jluna have no architectural design in common, jluna was created completely independently and does not mimic any of CxxWrap.jl features directly, and vice-versa. Whether this is advantageous or disadvantageous depends on the individual user and application.

Lastly, a much more minor difference is that jluna was designed from the ground up using C++20 techniques such as concepts, making it’s C++ code much more modern. In exchange for the nicer syntax and future-proofing, jluna requires up-to-date compilers.

CxxInterface.jl / CxxCall.jl

CxxInterface.jl and CxxCall.jl both aim to call C++ functions (contained in a shared library) from Julia. They essentially are a ccall for C++, not a full language wrapper, the projects are therefore not functionally equivalent. jluna does provide a way for the julia state to call any C++ function, the mechanism to achieve this is completely different, however.

---

In summary, the only fully functional equivalent for jluna is the Julia C-API, as only it provides a Julia-wrapper that assumes C / C++ as the host language. It is therefore the superior choice in projects where Julia plays an auxiliary rule while C++ is more dominant, as jluna provides clearer design, more documentation and overall ease-of-use when compared to the C-API.

---

FAQ: Is it done / fast yet?

jluna is feature-complete as of 0.9.0. This release also included extensive benchmarking, quantifying jlunas performance and proving its capability for excellent performance. Correctness is assured through automated testing.

1.0 released in February 2023, as of that release, Windows support is no longer experimental, and Windows machines are now fully supported.

---

FAQ: Did you know Julia 1.9 will include foreign thread support?

I am aware that with the release of Julia 1.9 basically the entire multi-threading module will have to be deprecated. Until then, multi-threading should still be supported for less up-to-date machines, however, developers using jluna should be aware that the multi-threading module (and only it) may be marked for deletion at some point. For all other library features, jluna guarantees version continuity and backwards compatibility.