<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Embedding Julia — Julia Language 0.3.4 documentation</title>
<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="../_static/julia.css" type="text/css" />
<link rel="stylesheet" href="../_static/julia.css" type="text/css" />
<link rel="top" title="Julia Language 0.3.4 documentation" href="../index.html"/>
<link rel="next" title="Packages" href="packages.html"/>
<link rel="prev" title="Interacting With Julia" href="interacting-with-julia.html"/>
<script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="http://julialang.org/"><img src="../_static/julia-logo.svg" class="logo"></a>
<!--
<a href="../index.html" class="fa fa-home"> Julia Language</a>
-->
<div role="search">
<form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="getting-started.html#resources">Resources</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="variables.html#allowed-variable-names">Allowed Variable Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="variables.html#stylistic-conventions">Stylistic Conventions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="integers-and-floating-point-numbers.html">Integers and Floating-Point Numbers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#integers">Integers</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#floating-point-numbers">Floating-Point Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#arbitrary-precision-arithmetic">Arbitrary Precision Arithmetic</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#numeric-literal-coefficients">Numeric Literal Coefficients</a></li>
<li class="toctree-l2"><a class="reference internal" href="integers-and-floating-point-numbers.html#literal-zero-and-one">Literal zero and one</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="mathematical-operations.html">Mathematical Operations and Elementary Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#arithmetic-operators">Arithmetic Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#bitwise-operators">Bitwise Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#updating-operators">Updating operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#numeric-comparisons">Numeric Comparisons</a></li>
<li class="toctree-l2"><a class="reference internal" href="mathematical-operations.html#elementary-functions">Elementary Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="complex-and-rational-numbers.html">Complex and Rational Numbers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="complex-and-rational-numbers.html#complex-numbers">Complex Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="complex-and-rational-numbers.html#rational-numbers">Rational Numbers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="strings.html">Strings</a><ul>
<li class="toctree-l2"><a class="reference internal" href="strings.html#characters">Characters</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#string-basics">String Basics</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#unicode-and-utf-8">Unicode and UTF-8</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#interpolation">Interpolation</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#common-operations">Common Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#non-standard-string-literals">Non-Standard String Literals</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#regular-expressions">Regular Expressions</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#id3">Byte Array Literals</a></li>
<li class="toctree-l2"><a class="reference internal" href="strings.html#version-number-literals">Version Number Literals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="functions.html">Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="functions.html#argument-passing-behavior">Argument Passing Behavior</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#the-return-keyword">The <tt class="docutils literal"><span class="pre">return</span></tt> Keyword</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#id1">Operators Are Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#operators-with-special-names">Operators With Special Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#anonymous-functions">Anonymous Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#multiple-return-values">Multiple Return Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#varargs-functions">Varargs Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#optional-arguments">Optional Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#keyword-arguments">Keyword Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#evaluation-scope-of-default-values">Evaluation Scope of Default Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#block-syntax-for-function-arguments">Block Syntax for Function Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="functions.html#further-reading">Further Reading</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="control-flow.html">Control Flow</a><ul>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#compound-expressions">Compound Expressions</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#conditional-evaluation">Conditional Evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#short-circuit-evaluation">Short-Circuit Evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#repeated-evaluation-loops">Repeated Evaluation: Loops</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#exception-handling">Exception Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="control-flow.html#tasks-aka-coroutines">Tasks (aka Coroutines)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="variables-and-scoping.html">Scope of Variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="variables-and-scoping.html#for-loops-and-comprehensions">For Loops and Comprehensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="variables-and-scoping.html#constants">Constants</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="types.html">Types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-declarations">Type Declarations</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#abstract-types">Abstract Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#bits-types">Bits Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#composite-types">Composite Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#immutable-composite-types">Immutable Composite Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#declared-types">Declared Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#tuple-types">Tuple Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-unions">Type Unions</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#man-parametric-types">Parametric Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#type-aliases">Type Aliases</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html#operations-on-types">Operations on Types</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="methods.html">Methods</a><ul>
<li class="toctree-l2"><a class="reference internal" href="methods.html#defining-methods">Defining Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#method-ambiguities">Method Ambiguities</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#parametric-methods">Parametric Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="methods.html#note-on-optional-and-keyword-arguments">Note on Optional and keyword Arguments</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="constructors.html">Constructors</a><ul>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#outer-constructor-methods">Outer Constructor Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#inner-constructor-methods">Inner Constructor Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#incomplete-initialization">Incomplete Initialization</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#parametric-constructors">Parametric Constructors</a></li>
<li class="toctree-l2"><a class="reference internal" href="constructors.html#case-study-rational">Case Study: Rational</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="conversion-and-promotion.html">Conversion and Promotion</a><ul>
<li class="toctree-l2"><a class="reference internal" href="conversion-and-promotion.html#conversion">Conversion</a></li>
<li class="toctree-l2"><a class="reference internal" href="conversion-and-promotion.html#promotion">Promotion</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="modules.html">Modules</a><ul>
<li class="toctree-l2"><a class="reference internal" href="modules.html#summary-of-module-usage">Summary of module usage</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="metaprogramming.html">Metaprogramming</a><ul>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#expressions-and-eval">Expressions and Eval</a></li>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="metaprogramming.html#reflection">Reflection</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="arrays.html">Multi-dimensional Arrays</a><ul>
<li class="toctree-l2"><a class="reference internal" href="arrays.html#arrays">Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="arrays.html#sparse-matrices">Sparse Matrices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="linear-algebra.html">Linear algebra</a><ul>
<li class="toctree-l2"><a class="reference internal" href="linear-algebra.html#matrix-factorizations">Matrix factorizations</a></li>
<li class="toctree-l2"><a class="reference internal" href="linear-algebra.html#special-matrices">Special matrices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="networking-and-streams.html">Networking and Streams</a><ul>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#basic-stream-i-o">Basic Stream I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#text-i-o">Text I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#working-with-files">Working with Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#a-simple-tcp-example">A simple TCP example</a></li>
<li class="toctree-l2"><a class="reference internal" href="networking-and-streams.html#resolving-ip-addresses">Resolving IP Addresses</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="parallel-computing.html">Parallel Computing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#data-movement">Data Movement</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#parallel-map-and-loops">Parallel Map and Loops</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#synchronization-with-remote-references">Synchronization With Remote References</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#scheduling">Scheduling</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#distributed-arrays">Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#constructing-distributed-arrays">Constructing Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#distributed-array-operations">Distributed Array Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#shared-arrays-experimental">Shared Arrays (Experimental)</a></li>
<li class="toctree-l2"><a class="reference internal" href="parallel-computing.html#clustermanagers">ClusterManagers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="running-external-programs.html">Running External Programs</a><ul>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#interpolation">Interpolation</a></li>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#quoting">Quoting</a></li>
<li class="toctree-l2"><a class="reference internal" href="running-external-programs.html#pipelines">Pipelines</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="calling-c-and-fortran-code.html">Calling C and Fortran Code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#mapping-c-types-to-julia">Mapping C Types to Julia</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#accessing-data-through-a-pointer">Accessing Data through a Pointer</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#passing-pointers-for-modifying-inputs">Passing Pointers for Modifying Inputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#garbage-collection-safety">Garbage Collection Safety</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#non-constant-function-specifications">Non-constant Function Specifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#indirect-calls">Indirect Calls</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#calling-convention">Calling Convention</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#accessing-global-variables">Accessing Global Variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#passing-julia-callback-functions-to-c">Passing Julia Callback Functions to C</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#c">C++</a></li>
<li class="toctree-l2"><a class="reference internal" href="calling-c-and-fortran-code.html#handling-platform-variations">Handling Platform Variations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="interacting-with-julia.html">Interacting With Julia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="interacting-with-julia.html#the-different-prompt-modes">The different prompt modes</a></li>
<li class="toctree-l2"><a class="reference internal" href="interacting-with-julia.html#key-bindings">Key bindings</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Embedding Julia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#high-level-embedding">High-Level Embedding</a></li>
<li class="toctree-l2"><a class="reference internal" href="#converting-types">Converting Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="#calling-julia-functions">Calling Julia Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#memory-management">Memory Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="#working-with-arrays">Working with Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="#exceptions">Exceptions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="packages.html">Packages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="packages.html#package-status">Package Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#adding-and-removing-packages">Adding and Removing Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#installing-unregistered-packages">Installing Unregistered Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#updating-packages">Updating Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#checkout-pin-and-free">Checkout, Pin and Free</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="packages.html#package-development">Package Development</a><ul>
<li class="toctree-l2"><a class="reference internal" href="packages.html#initial-setup">Initial Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#generating-a-new-package">Generating a New Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#making-your-package-available">Making Your Package Available</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#publishing-your-package">Publishing Your Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#tagging-package-versions">Tagging Package Versions</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#fixing-package-requirements">Fixing Package Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="packages.html#man-package-requirements">Requirements Specification</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="performance-tips.html">Performance Tips</a><ul>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-global-variables">Avoid global variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#measure-performance-with-time-and-pay-attention-to-memory-allocation">Measure performance with <tt class="docutils literal"><span class="pre">@time</span></tt> and pay attention to memory allocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#tools">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-containers-with-abstract-type-parameters">Avoid containers with abstract type parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#type-declarations">Type declarations</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#break-functions-into-multiple-definitions">Break functions into multiple definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#write-type-stable-functions">Write “type-stable” functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-changing-the-type-of-a-variable">Avoid changing the type of a variable</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#separate-kernel-functions">Separate kernel functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#access-arrays-in-memory-order-along-columns">Access arrays in memory order, along columns</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#pre-allocating-outputs">Pre-allocating outputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#avoid-string-interpolation-for-i-o">Avoid string interpolation for I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#fix-deprecation-warnings">Fix deprecation warnings</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#tweaks">Tweaks</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance-tips.html#performance-annotations">Performance Annotations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="style-guide.html">Style Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#write-functions-not-just-scripts">Write functions, not just scripts</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-writing-overly-specific-types">Avoid writing overly-specific types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#handle-excess-argument-diversity-in-the-caller">Handle excess argument diversity in the caller</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#append-to-names-of-functions-that-modify-their-arguments">Append <cite>!</cite> to names of functions that modify their arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-strange-type-unions">Avoid strange type Unions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#try-to-avoid-nullable-fields">Try to avoid nullable fields</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-elaborate-container-types">Avoid elaborate container types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-underscores-in-names">Avoid underscores in names</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse-try-catch">Don’t overuse try-catch</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-parenthesize-conditions">Don’t parenthesize conditions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse">Don’t overuse ...</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-use-unnecessary-static-parameters">Don’t use unnecessary static parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#avoid-confusion-about-whether-something-is-an-instance-or-a-type">Avoid confusion about whether something is an instance or a type</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overuse-macros">Don’t overuse macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-expose-unsafe-operations-at-the-interface-level">Don’t expose unsafe operations at the interface level</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#don-t-overload-methods-of-base-container-types">Don’t overload methods of base container types</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#be-careful-with-type-equality">Be careful with type equality</a></li>
<li class="toctree-l2"><a class="reference internal" href="style-guide.html#do-not-write-x-f-x">Do not write <tt class="docutils literal"><span class="pre">x->f(x)</span></tt></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="faq.html#sessions-and-the-repl">Sessions and the REPL</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#functions">Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#types-type-declarations-and-constructors">Types, type declarations, and constructors</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#nothingness-and-missing-values">Nothingness and missing values</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#julia-releases">Julia Releases</a></li>
<li class="toctree-l2"><a class="reference internal" href="faq.html#developing-julia">Developing Julia</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="noteworthy-differences.html">Noteworthy Differences from other Languages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-matlab">Noteworthy differences from MATLAB</a></li>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-r">Noteworthy differences from R</a></li>
<li class="toctree-l2"><a class="reference internal" href="noteworthy-differences.html#noteworthy-differences-from-python">Noteworthy differences from Python</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/base.html">The Standard Library</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#getting-around">Getting Around</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#all-objects">All Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#types">Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#generic-functions">Generic Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#syntax">Syntax</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#iteration">Iteration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#general-collections">General Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#iterable-collections">Iterable Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#indexable-collections">Indexable Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#associative-collections">Associative Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#set-like-collections">Set-Like Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#dequeues">Dequeues</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#strings">Strings</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#i-o">I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#network-i-o">Network I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#text-i-o">Text I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#multimedia-i-o">Multimedia I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#memory-mapped-i-o">Memory-mapped I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#standard-numeric-types">Standard Numeric Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#mathematical-operators">Mathematical Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#mathematical-functions">Mathematical Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#data-formats">Data Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#numbers">Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#bigfloats">BigFloats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#random-numbers">Random Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#arrays">Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#combinatorics">Combinatorics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#statistics">Statistics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#signal-processing">Signal Processing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#numerical-integration">Numerical Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#parallel-computing">Parallel Computing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#distributed-arrays">Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#shared-arrays-experimental-unix-only-feature">Shared Arrays (Experimental, UNIX-only feature)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#system">System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#c-interface">C Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#errors">Errors</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#tasks">Tasks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#events">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#reflection">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#internals">Internals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/sparse.html">Sparse Matrices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/linalg.html">Linear Algebra</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/linalg.html#module-Base.LinAlg.BLAS">BLAS Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/constants.html">Constants</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/file.html">Filesystem</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/punctuation.html">Punctuation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/sort.html">Sorting and Related Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#sorting-functions">Sorting Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#order-related-functions">Order-Related Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#sorting-algorithms">Sorting Algorithms</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/pkg.html">Package Manager Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/collections.html">Collections and Data Structures</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/collections.html#priorityqueue">PriorityQueue</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/collections.html#heap-functions">Heap Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/graphics.html">Graphics</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/graphics.html#geometry">Geometry</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/test.html">Unit and Functional Testing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#handlers">Handlers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#functions">Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/test.html#testing-base-julia">Testing Base Julia</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/profile.html">Profiling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#basic-usage">Basic usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#accumulation-and-clearing">Accumulation and clearing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#options-for-controlling-the-display-of-profile-results">Options for controlling the display of profile results</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#configuration">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#function-reference">Function reference</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../devdocs/julia.html">Documentation of Julia’s Internals</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/cartesian.html">Base.Cartesian</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/sysimg.html">System Image Building</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../devdocs/C.html">Developing/debugging Julia’s C code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/backtraces.html">Reporting and analyzing crashes (segfaults)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devdocs/debuggingtips.html">gdb debugging tips</a></li>
</ul>
</li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Julia Language</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> »</li>
<li>Embedding Julia</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/manual/embedding.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document">
<div class="section" id="embedding-julia">
<h1>Embedding Julia<a class="headerlink" href="#embedding-julia" title="Permalink to this headline">¶</a></h1>
<p>As we have seen (<a class="reference internal" href="calling-c-and-fortran-code.html#man-calling-c-and-fortran-code"><em>Calling C and Fortran Code</em></a>) Julia has a simple and efficient way to call functions written in C. But there are situations where the opposite is needed: calling Julia function from C code. This can be used to integrate Julia code into a larger C/C++ project, without the need to rewrite everything in C/C++. Julia has a C API to make this possible. As almost all programming languages have some way to call C functions, the Julia C API can also be used to build further language bridges (e.g. calling Julia from Python or C#).</p>
<div class="section" id="high-level-embedding">
<h2>High-Level Embedding<a class="headerlink" href="#high-level-embedding" title="Permalink to this headline">¶</a></h2>
<p>We start with a simple C program that initializes Julia and calls some Julia code:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <julia.h></span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span>
<span class="p">{</span>
<span class="n">jl_init</span><span class="p">(</span><span class="nb">NULL</span><span class="p">);</span>
<span class="n">JL_SET_STACK_BASE</span><span class="p">;</span>
<span class="n">jl_eval_string</span><span class="p">(</span><span class="s">"print(sqrt(2.0))"</span><span class="p">);</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In order to build this program you have to put the path to the Julia header into the include path and link against <tt class="docutils literal"><span class="pre">libjulia</span></tt>. For instance, when Julia is installed to <tt class="docutils literal"><span class="pre">$JULIA_DIR</span></tt>, one can compile the above test program <tt class="docutils literal"><span class="pre">test.c</span></tt> with gcc using:</p>
<div class="highlight-c"><pre>gcc -o test -I$JULIA_DIR/include/julia -L$JULIA_DIR/usr/lib -ljulia test.c</pre>
</div>
<p>Alternatively, look at the <tt class="docutils literal"><span class="pre">embedding.c</span></tt> program in the julia source tree in the <tt class="docutils literal"><span class="pre">examples/</span></tt> folder.</p>
<p>The first thing that has to be done before calling any other Julia C function is to initialize Julia. This is done by calling <tt class="docutils literal"><span class="pre">jl_init</span></tt>, which takes as argument a C string (<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt>) to the location where Julia is installed. When the argument is <tt class="docutils literal"><span class="pre">NULL</span></tt>, Julia tries to determine the install location automatically.</p>
<p>The second statement initializes Julia’s task scheduling system. This statement must appear in a function that will not return as long as calls into Julia will be made (<tt class="docutils literal"><span class="pre">main</span></tt> works fine). Strictly speaking, this statement is optional, but operations that switch tasks will cause problems if it is omitted.</p>
<p>The third statement in the test program evaluates a Julia statement using a call to <tt class="docutils literal"><span class="pre">jl_eval_string</span></tt>.</p>
</div>
<div class="section" id="converting-types">
<h2>Converting Types<a class="headerlink" href="#converting-types" title="Permalink to this headline">¶</a></h2>
<p>Real applications will not just need to execute expressions, but also return their values to the host program. <tt class="docutils literal"><span class="pre">jl_eval_string</span></tt> returns a <tt class="docutils literal"><span class="pre">jl_value_t*</span></tt>, which is a pointer to a heap-allocated Julia object. Storing simple data types like <tt class="docutils literal"><span class="pre">Float64</span></tt> in this way is called <tt class="docutils literal"><span class="pre">boxing</span></tt>, and extracting the stored primitive data is called <tt class="docutils literal"><span class="pre">unboxing</span></tt>. Our improved sample program that calculates the square root of 2 in Julia and reads back the result in C looks as follows:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">ret</span> <span class="o">=</span> <span class="n">jl_eval_string</span><span class="p">(</span><span class="s">"sqrt(2.0)"</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">jl_is_float64</span><span class="p">(</span><span class="n">ret</span><span class="p">))</span> <span class="p">{</span>
<span class="kt">double</span> <span class="n">ret_unboxed</span> <span class="o">=</span> <span class="n">jl_unbox_float64</span><span class="p">(</span><span class="n">ret</span><span class="p">);</span>
<span class="n">printf</span><span class="p">(</span><span class="s">"sqrt(2.0) in C: %e </span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">ret_unboxed</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In order to check whether <tt class="docutils literal"><span class="pre">ret</span></tt> is of a specific Julia type, we can use the <tt class="docutils literal"><span class="pre">jl_is_...</span></tt> functions. By typing <tt class="docutils literal"><span class="pre">typeof(sqrt(2.0))</span></tt> into the Julia shell we can see that the return type is <tt class="docutils literal"><span class="pre">Float64</span></tt> (<tt class="docutils literal"><span class="pre">double</span></tt> in C). To convert the boxed Julia value into a C double the <tt class="docutils literal"><span class="pre">jl_unbox_float64</span></tt> function is used in the above code snippet.</p>
<p>Corresponding <tt class="docutils literal"><span class="pre">jl_box_...</span></tt> functions are used to convert the other way:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">a</span> <span class="o">=</span> <span class="n">jl_box_float64</span><span class="p">(</span><span class="mf">3.0</span><span class="p">);</span>
<span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">b</span> <span class="o">=</span> <span class="n">jl_box_float32</span><span class="p">(</span><span class="mf">3.0f</span><span class="p">);</span>
<span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">c</span> <span class="o">=</span> <span class="n">jl_box_int32</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span>
</pre></div>
</div>
<p>As we will see next, boxing is required to call Julia functions with specific arguments.</p>
</div>
<div class="section" id="calling-julia-functions">
<h2>Calling Julia Functions<a class="headerlink" href="#calling-julia-functions" title="Permalink to this headline">¶</a></h2>
<p>While <tt class="docutils literal"><span class="pre">jl_eval_string</span></tt> allows C to obtain the result of a Julia expression, it does not allow passing arguments computed in C to Julia. For this you will need to invoke Julia functions directly, using <tt class="docutils literal"><span class="pre">jl_call</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_function_t</span> <span class="o">*</span><span class="n">func</span> <span class="o">=</span> <span class="n">jl_get_function</span><span class="p">(</span><span class="n">jl_base_module</span><span class="p">,</span> <span class="s">"sqrt"</span><span class="p">);</span>
<span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">argument</span> <span class="o">=</span> <span class="n">jl_box_float64</span><span class="p">(</span><span class="mf">2.0</span><span class="p">);</span>
<span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">ret</span> <span class="o">=</span> <span class="n">jl_call1</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">argument</span><span class="p">);</span>
</pre></div>
</div>
<p>In the first step, a handle to the Julia function <tt class="docutils literal"><span class="pre">sqrt</span></tt> is retrieved by calling <tt class="docutils literal"><span class="pre">jl_get_function</span></tt>. The first argument passed to <tt class="docutils literal"><span class="pre">jl_get_function</span></tt> is a pointer to the <tt class="docutils literal"><span class="pre">Base</span></tt> module in which <tt class="docutils literal"><span class="pre">sqrt</span></tt> is defined. Then, the double value is boxed using <tt class="docutils literal"><span class="pre">jl_box_float64</span></tt>. Finally, in the last step, the function is called using <tt class="docutils literal"><span class="pre">jl_call1</span></tt>. <tt class="docutils literal"><span class="pre">jl_call0</span></tt>, <tt class="docutils literal"><span class="pre">jl_call2</span></tt>, and <tt class="docutils literal"><span class="pre">jl_call3</span></tt> functions also exist, to conveniently handle different numbers of arguments. To pass more arguments, use <tt class="docutils literal"><span class="pre">jl_call</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">jl_call</span><span class="p">(</span><span class="kt">jl_function_t</span> <span class="o">*</span><span class="n">f</span><span class="p">,</span> <span class="kt">jl_value_t</span> <span class="o">**</span><span class="n">args</span><span class="p">,</span> <span class="kt">int32_t</span> <span class="n">nargs</span><span class="p">)</span>
</pre></div>
</div>
<p>Its second argument <tt class="docutils literal"><span class="pre">args</span></tt> is an array of <tt class="docutils literal"><span class="pre">jl_value_t*</span></tt> arguments and <tt class="docutils literal"><span class="pre">nargs</span></tt> is the number of arguments.</p>
</div>
<div class="section" id="memory-management">
<h2>Memory Management<a class="headerlink" href="#memory-management" title="Permalink to this headline">¶</a></h2>
<p>As we have seen, Julia objects are represented in C as pointers. This raises the question of who is responsible for freeing these objects.</p>
<p>Typically, Julia objects are freed by a garbage collector (GC), but the GC does not automatically know that we are holding a reference to a Julia value from C. This means the GC can free objects out from under you, rendering pointers invalid.</p>
<p>The GC can only run when Julia objects are allocated. Calls like <tt class="docutils literal"><span class="pre">jl_box_float64</span></tt> perform allocation, and allocation might also happen at any point in running Julia code. However, it is generally safe to use pointers in between <tt class="docutils literal"><span class="pre">jl_...</span></tt> calls. But in order to make sure that values can survive <tt class="docutils literal"><span class="pre">jl_...</span></tt> calls, we have to tell Julia that we hold a reference to a Julia value. This can be done using the <tt class="docutils literal"><span class="pre">JL_GC_PUSH</span></tt> macros:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">ret</span> <span class="o">=</span> <span class="n">jl_eval_string</span><span class="p">(</span><span class="s">"sqrt(2.0)"</span><span class="p">);</span>
<span class="n">JL_GC_PUSH1</span><span class="p">(</span><span class="o">&</span><span class="n">ret</span><span class="p">);</span>
<span class="c1">// Do something with ret</span>
<span class="n">JL_GC_POP</span><span class="p">();</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">JL_GC_POP</span></tt> call releases the references established by the previous <tt class="docutils literal"><span class="pre">JL_GC_PUSH</span></tt>. Note that <tt class="docutils literal"><span class="pre">JL_GC_PUSH</span></tt> is working on the stack, so it must be exactly paired with a <tt class="docutils literal"><span class="pre">JL_GC_POP</span></tt> before the stack frame is destroyed.</p>
<p>Several Julia values can be pushed at once using the <tt class="docutils literal"><span class="pre">JL_GC_PUSH2</span></tt> , <tt class="docutils literal"><span class="pre">JL_GC_PUSH3</span></tt> , and <tt class="docutils literal"><span class="pre">JL_GC_PUSH4</span></tt> macros. To push an array of Julia values one can use the <tt class="docutils literal"><span class="pre">JL_GC_PUSHARGS</span></tt> macro, which can be used as follows:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_value_t</span> <span class="o">**</span><span class="n">args</span><span class="p">;</span>
<span class="n">JL_GC_PUSHARGS</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span> <span class="c1">// args can now hold 2 `jl_value_t*` objects</span>
<span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">some_value</span><span class="p">;</span>
<span class="n">args</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">some_other_value</span><span class="p">;</span>
<span class="c1">// Do something with args (e.g. call jl_... functions)</span>
<span class="n">JL_GC_POP</span><span class="p">();</span>
</pre></div>
</div>
<div class="section" id="manipulating-the-garbage-collector">
<h3>Manipulating the Garbage Collector<a class="headerlink" href="#manipulating-the-garbage-collector" title="Permalink to this headline">¶</a></h3>
<p>There are some functions to control the GC. In normal use cases, these should not be necessary.</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="76%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">void</span> <span class="pre">jl_gc_collect()</span></tt></td>
<td>Force a GC run</td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">void</span> <span class="pre">jl_gc_disable()</span></tt></td>
<td>Disable the GC</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">void</span> <span class="pre">jl_gc_enable()</span></tt></td>
<td>Enable the GC</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="working-with-arrays">
<h2>Working with Arrays<a class="headerlink" href="#working-with-arrays" title="Permalink to this headline">¶</a></h2>
<p>Julia and C can share array data without copying. The next example will show how this works.</p>
<p>Julia arrays are represented in C by the datatype <tt class="docutils literal"><span class="pre">jl_array_t*</span></tt>. Basically, <tt class="docutils literal"><span class="pre">jl_array_t</span></tt> is a struct that contains:</p>
<ul class="simple">
<li>Information about the datatype</li>
<li>A pointer to the data block</li>
<li>Information about the sizes of the array</li>
</ul>
<p>To keep things simple, we start with a 1D array. Creating an array containing Float64 elements of length 10 is done by:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_value_t</span><span class="o">*</span> <span class="n">array_type</span> <span class="o">=</span> <span class="n">jl_apply_array_type</span><span class="p">(</span><span class="n">jl_float64_type</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>
<span class="kt">jl_array_t</span><span class="o">*</span> <span class="n">x</span> <span class="o">=</span> <span class="n">jl_alloc_array_1d</span><span class="p">(</span><span class="n">array_type</span><span class="p">,</span> <span class="mi">10</span><span class="p">);</span>
</pre></div>
</div>
<p>Alternatively, if you have already allocated the array you can generate a thin wrapper around its data:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">double</span> <span class="o">*</span><span class="n">existingArray</span> <span class="o">=</span> <span class="p">(</span><span class="kt">double</span><span class="o">*</span><span class="p">)</span><span class="n">malloc</span><span class="p">(</span><span class="k">sizeof</span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="o">*</span><span class="mi">10</span><span class="p">);</span>
<span class="kt">jl_array_t</span> <span class="o">*</span><span class="n">x</span> <span class="o">=</span> <span class="n">jl_ptr_to_array_1d</span><span class="p">(</span><span class="n">array_type</span><span class="p">,</span> <span class="n">existingArray</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
</pre></div>
</div>
<p>The last argument is a boolean indicating whether Julia should take ownership of the data. If this argument is non-zero, the GC will call <tt class="docutils literal"><span class="pre">free</span></tt> on the data pointer when the array is no longer referenced.</p>
<p>In order to access the data of x, we can use <tt class="docutils literal"><span class="pre">jl_array_data</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">double</span> <span class="o">*</span><span class="n">xData</span> <span class="o">=</span> <span class="p">(</span><span class="kt">double</span><span class="o">*</span><span class="p">)</span><span class="n">jl_array_data</span><span class="p">(</span><span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>Now we can fill the array:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">for</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">i</span><span class="o"><</span><span class="n">jl_array_len</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span>
<span class="n">xData</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span>
</pre></div>
</div>
<p>Now let us call a Julia function that performs an in-place operation on <tt class="docutils literal"><span class="pre">x</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_function_t</span> <span class="o">*</span><span class="n">func</span> <span class="o">=</span> <span class="n">jl_get_function</span><span class="p">(</span><span class="n">jl_base_module</span><span class="p">,</span> <span class="s">"reverse!"</span><span class="p">);</span>
<span class="n">jl_call1</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="p">(</span><span class="kt">jl_value_t</span><span class="o">*</span><span class="p">)</span><span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>By printing the array, one can verify that the elements of <tt class="docutils literal"><span class="pre">x</span></tt> are now reversed.</p>
<div class="section" id="accessing-returned-arrays">
<h3>Accessing Returned Arrays<a class="headerlink" href="#accessing-returned-arrays" title="Permalink to this headline">¶</a></h3>
<p>If a Julia function returns an array, the return value of <tt class="docutils literal"><span class="pre">jl_eval_string</span></tt> and <tt class="docutils literal"><span class="pre">jl_call</span></tt> can be cast to a <tt class="docutils literal"><span class="pre">jl_array_t*</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">jl_function_t</span> <span class="o">*</span><span class="n">func</span> <span class="o">=</span> <span class="n">jl_get_function</span><span class="p">(</span><span class="n">jl_base_module</span><span class="p">,</span> <span class="s">"reverse"</span><span class="p">);</span>
<span class="kt">jl_array_t</span> <span class="o">*</span><span class="n">y</span> <span class="o">=</span> <span class="p">(</span><span class="kt">jl_array_t</span><span class="o">*</span><span class="p">)</span><span class="n">jl_call1</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="p">(</span><span class="kt">jl_value_t</span><span class="o">*</span><span class="p">)</span><span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>Now the content of <tt class="docutils literal"><span class="pre">y</span></tt> can be accessed as before using <tt class="docutils literal"><span class="pre">jl_array_data</span></tt>.
As always, be sure to keep a reference to the array while it is in use.</p>
</div>
<div class="section" id="multidimensional-arrays">
<h3>Multidimensional Arrays<a class="headerlink" href="#multidimensional-arrays" title="Permalink to this headline">¶</a></h3>
<p>Julia’s multidimensional arrays are stored in memory in column-major order. Here is some code that creates a 2D array and accesses its properties:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="c1">// Create 2D array of float64 type</span>
<span class="kt">jl_value_t</span> <span class="o">*</span><span class="n">array_type</span> <span class="o">=</span> <span class="n">jl_apply_array_type</span><span class="p">(</span><span class="n">jl_float64_type</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="kt">jl_array_t</span> <span class="o">*</span><span class="n">x</span> <span class="o">=</span> <span class="n">jl_alloc_array_2d</span><span class="p">(</span><span class="n">array_type</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">5</span><span class="p">);</span>
<span class="c1">// Get array pointer</span>
<span class="kt">double</span> <span class="o">*</span><span class="n">p</span> <span class="o">=</span> <span class="p">(</span><span class="kt">double</span><span class="o">*</span><span class="p">)</span><span class="n">jl_array_data</span><span class="p">(</span><span class="n">x</span><span class="p">);</span>
<span class="c1">// Get number of dimensions</span>
<span class="kt">int</span> <span class="n">ndims</span> <span class="o">=</span> <span class="n">jl_array_ndims</span><span class="p">(</span><span class="n">x</span><span class="p">);</span>
<span class="c1">// Get the size of the i-th dim</span>
<span class="kt">size_t</span> <span class="n">size0</span> <span class="o">=</span> <span class="n">jl_array_dim</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="mi">0</span><span class="p">);</span>
<span class="kt">size_t</span> <span class="n">size1</span> <span class="o">=</span> <span class="n">jl_array_dim</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="mi">1</span><span class="p">);</span>
<span class="c1">// Fill array with data</span>
<span class="k">for</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">i</span><span class="o"><</span><span class="n">size1</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span>
<span class="k">for</span><span class="p">(</span><span class="kt">size_t</span> <span class="n">j</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">j</span><span class="o"><</span><span class="n">size0</span><span class="p">;</span> <span class="n">j</span><span class="o">++</span><span class="p">)</span>
<span class="n">p</span><span class="p">[</span><span class="n">j</span> <span class="o">+</span> <span class="n">size0</span><span class="o">*</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span> <span class="o">+</span> <span class="n">j</span><span class="p">;</span>
</pre></div>
</div>
<p>Notice that while Julia arrays use 1-based indexing, the C API uses 0-based indexing (for example in calling <tt class="docutils literal"><span class="pre">jl_array_dim</span></tt>) in order to read as idiomatic C code.</p>
</div>
</div>
<div class="section" id="exceptions">
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2>
<p>Julia code can throw exceptions. For example, consider:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">jl_eval_string</span><span class="p">(</span><span class="s">"this_function_does_not_exist()"</span><span class="p">);</span>
</pre></div>
</div>
<p>This call will appear to do nothing. However, it is possible to check whether an exception was thrown:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">jl_exception_occurred</span><span class="p">())</span>
<span class="n">printf</span><span class="p">(</span><span class="s">"%s </span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">jl_typeof_str</span><span class="p">(</span><span class="n">jl_exception_occurred</span><span class="p">()));</span>
</pre></div>
</div>
<p>If you are using the Julia C API from a language that supports exceptions (e.g. Python, C#, C++), it makes sense to wrap each call into libjulia with a function that checks whether an exception was thrown, and then rethrows the exception in the host language.</p>
<div class="section" id="throwing-julia-exceptions">
<h3>Throwing Julia Exceptions<a class="headerlink" href="#throwing-julia-exceptions" title="Permalink to this headline">¶</a></h3>
<p>When writing Julia callable functions, it might be necessary to validate arguments and throw exceptions to indicate errors. A typical type check looks like:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">jl_is_float64</span><span class="p">(</span><span class="n">val</span><span class="p">))</span> <span class="p">{</span>
<span class="n">jl_type_error</span><span class="p">(</span><span class="n">function_name</span><span class="p">,</span> <span class="p">(</span><span class="kt">jl_value_t</span><span class="o">*</span><span class="p">)</span><span class="n">jl_float64_type</span><span class="p">,</span> <span class="n">val</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>General exceptions can be raised using the funtions:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">jl_error</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">str</span><span class="p">);</span>
<span class="kt">void</span> <span class="nf">jl_errorf</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">fmt</span><span class="p">,</span> <span class="p">...);</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">jl_error</span></tt> takes a C string, and <tt class="docutils literal"><span class="pre">jl_errorf</span></tt> is called like <tt class="docutils literal"><span class="pre">printf</span></tt>:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">jl_errorf</span><span class="p">(</span><span class="s">"argument x = %d is too large"</span><span class="p">,</span> <span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>where in this example <tt class="docutils literal"><span class="pre">x</span></tt> is assumed to be an integer.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="packages.html" class="btn btn-neutral float-right" title="Packages"/>Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="interacting-with-julia.html" class="btn btn-neutral" title="Interacting With Julia"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
</p>
</div>
<a href="https://github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'0.3.4',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
