17 lines
16 KiB
HTML
17 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Bounds checking · The Julia Language</title><script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-28835595-6', 'auto');
|
|
ga('send', 'pageview');
|
|
</script><link href="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css" rel="stylesheet" type="text/css"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link href="../assets/documenter.css" rel="stylesheet" type="text/css"/><link href="../assets/julia-manual.css" rel="stylesheet" type="text/css"/></head><body><nav class="toc"><a href="../index.html"><img class="logo" src="../assets/logo.png" alt="The Julia Language logo"/></a><h1>The Julia Language</h1><select id="version-selector" onChange="window.location.href=this.value" style="visibility: hidden"></select><form class="search" id="search-form" action="../search.html"><input id="search-query" name="q" type="text" placeholder="Search docs"/></form><ul><li><a class="toctext" href="../index.html">Home</a></li><li><span class="toctext">Manual</span><ul><li><a class="toctext" href="../manual/introduction.html">Introduction</a></li><li><a class="toctext" href="../manual/getting-started.html">Getting Started</a></li><li><a class="toctext" href="../manual/variables.html">Variables</a></li><li><a class="toctext" href="../manual/integers-and-floating-point-numbers.html">Integers and Floating-Point Numbers</a></li><li><a class="toctext" href="../manual/mathematical-operations.html">Mathematical Operations and Elementary Functions</a></li><li><a class="toctext" href="../manual/complex-and-rational-numbers.html">Complex and Rational Numbers</a></li><li><a class="toctext" href="../manual/strings.html">Strings</a></li><li><a class="toctext" href="../manual/functions.html">Functions</a></li><li><a class="toctext" href="../manual/control-flow.html">Control Flow</a></li><li><a class="toctext" href="../manual/variables-and-scoping.html">Scope of Variables</a></li><li><a class="toctext" href="../manual/types.html">Types</a></li><li><a class="toctext" href="../manual/methods.html">Methods</a></li><li><a class="toctext" href="../manual/constructors.html">Constructors</a></li><li><a class="toctext" href="../manual/conversion-and-promotion.html">Conversion and Promotion</a></li><li><a class="toctext" href="../manual/interfaces.html">Interfaces</a></li><li><a class="toctext" href="../manual/modules.html">Modules</a></li><li><a class="toctext" href="../manual/documentation.html">Documentation</a></li><li><a class="toctext" href="../manual/metaprogramming.html">Metaprogramming</a></li><li><a class="toctext" href="../manual/arrays.html">Multi-dimensional Arrays</a></li><li><a class="toctext" href="../manual/linear-algebra.html">Linear algebra</a></li><li><a class="toctext" href="../manual/networking-and-streams.html">Networking and Streams</a></li><li><a class="toctext" href="../manual/parallel-computing.html">Parallel Computing</a></li><li><a class="toctext" href="../manual/dates.html">Date and DateTime</a></li><li><a class="toctext" href="../manual/interacting-with-julia.html">Interacting With Julia</a></li><li><a class="toctext" href="../manual/running-external-programs.html">Running External Programs</a></li><li><a class="toctext" href="../manual/calling-c-and-fortran-code.html">Calling C and Fortran Code</a></li><li><a class="toctext" href="../manual/handling-operating-system-variation.html">Handling Operating System Variation</a></li><li><a class="toctext" href="../manual/environment-variables.html">Environment Variables</a></li><li><a class="toctext" href="../manual/embedding.html">Embedding Julia</a></li><li><a class="toctext" href="../manual/packages.html">Packages</a></li><li><a class="toctext" href="../manual/profile.html">Profiling</a></li><li><a class="toctext" href="../manual/stacktraces.html">Stack Traces</a></li><li><a class="toctext" href="../manual/performance-tips.html">Performance Tips</a></li><li><a class="toctext" href="../manual/workflow-tips.html">Workflow Tips</a></li><li><a class="toctext" href="../manual/style-guide.html">Style Guide</a></li><li><a class="toctext" href="../manual/faq.html">Frequently Asked Questions</a></li><li><a class="toctext" href="../manual/noteworthy-differences.html">Noteworthy Differences from other Languages</a></li><li><a class="toctext" href="../manual/unicode-input.html">Unicode Input</a></li></ul></li><li><span class="toctext">Standard Library</span><ul><li><a class="toctext" href="../stdlib/base.html">Essentials</a></li><li><a class="toctext" href="../stdlib/collections.html">Collections and Data Structures</a></li><li><a class="toctext" href="../stdlib/math.html">Mathematics</a></li><li><a class="toctext" href="../stdlib/numbers.html">Numbers</a></li><li><a class="toctext" href="../stdlib/strings.html">Strings</a></li><li><a class="toctext" href="../stdlib/arrays.html">Arrays</a></li><li><a class="toctext" href="../stdlib/parallel.html">Tasks and Parallel Computing</a></li><li><a class="toctext" href="../stdlib/linalg.html">Linear Algebra</a></li><li><a class="toctext" href="../stdlib/constants.html">Constants</a></li><li><a class="toctext" href="../stdlib/file.html">Filesystem</a></li><li><a class="toctext" href="../stdlib/io-network.html">I/O and Network</a></li><li><a class="toctext" href="../stdlib/punctuation.html">Punctuation</a></li><li><a class="toctext" href="../stdlib/sort.html">Sorting and Related Functions</a></li><li><a class="toctext" href="../stdlib/pkg.html">Package Manager Functions</a></li><li><a class="toctext" href="../stdlib/dates.html">Dates and Time</a></li><li><a class="toctext" href="../stdlib/iterators.html">Iteration utilities</a></li><li><a class="toctext" href="../stdlib/test.html">Unit Testing</a></li><li><a class="toctext" href="../stdlib/c.html">C Interface</a></li><li><a class="toctext" href="../stdlib/libc.html">C Standard Library</a></li><li><a class="toctext" href="../stdlib/libdl.html">Dynamic Linker</a></li><li><a class="toctext" href="../stdlib/profile.html">Profiling</a></li><li><a class="toctext" href="../stdlib/stacktraces.html">StackTraces</a></li><li><a class="toctext" href="../stdlib/simd-types.html">SIMD Support</a></li></ul></li><li><span class="toctext">Developer Documentation</span><ul><li><a class="toctext" href="reflection.html">Reflection and introspection</a></li><li><span class="toctext">Documentation of Julia's Internals</span><ul><li><a class="toctext" href="init.html">Initialization of the Julia runtime</a></li><li><a class="toctext" href="ast.html">Julia ASTs</a></li><li><a class="toctext" href="types.html">More about types</a></li><li><a class="toctext" href="object.html">Memory layout of Julia Objects</a></li><li><a class="toctext" href="eval.html">Eval of Julia code</a></li><li><a class="toctext" href="callconv.html">Calling Conventions</a></li><li><a class="toctext" href="compiler.html">High-level Overview of the Native-Code Generation Process</a></li><li><a class="toctext" href="functions.html">Julia Functions</a></li><li><a class="toctext" href="cartesian.html">Base.Cartesian</a></li><li><a class="toctext" href="meta.html">Talking to the compiler (the <code>:meta</code> mechanism)</a></li><li><a class="toctext" href="subarrays.html">SubArrays</a></li><li><a class="toctext" href="sysimg.html">System Image Building</a></li><li><a class="toctext" href="llvm.html">Working with LLVM</a></li><li><a class="toctext" href="stdio.html">printf() and stdio in the Julia runtime</a></li><li class="current"><a class="toctext" href="boundscheck.html">Bounds checking</a><ul class="internal"><li><a class="toctext" href="#Eliding-bounds-checks-1">Eliding bounds checks</a></li><li><a class="toctext" href="#Propagating-inbounds-1">Propagating inbounds</a></li><li><a class="toctext" href="#The-bounds-checking-call-hierarchy-1">The bounds checking call hierarchy</a></li></ul></li><li><a class="toctext" href="locks.html">Proper maintenance and care of multi-threading locks</a></li><li><a class="toctext" href="offset-arrays.html">Arrays with custom indices</a></li><li><a class="toctext" href="libgit2.html">Base.LibGit2</a></li><li><a class="toctext" href="require.html">Module loading</a></li></ul></li><li><span class="toctext">Developing/debugging Julia's C code</span><ul><li><a class="toctext" href="backtraces.html">Reporting and analyzing crashes (segfaults)</a></li><li><a class="toctext" href="debuggingtips.html">gdb debugging tips</a></li><li><a class="toctext" href="valgrind.html">Using Valgrind with Julia</a></li><li><a class="toctext" href="sanitizers.html">Sanitizer support</a></li></ul></li></ul></li></ul></nav><article id="docs"><header><nav><ul><li>Developer Documentation</li><li>Documentation of Julia's Internals</li><li><a href="boundscheck.html">Bounds checking</a></li></ul><a class="edit-page" href="https://github.com/JuliaLang/julia/blob/master/doc/src/devdocs/boundscheck.md"><span class="fa"></span> Edit on GitHub</a></nav><hr/><div id="topbar"><span>Bounds checking</span><a class="fa fa-bars" href="#"></a></div></header><h1><a class="nav-anchor" id="Bounds-checking-1" href="#Bounds-checking-1">Bounds checking</a></h1><p>Like many modern programming languages, Julia uses bounds checking to ensure program safety when accessing arrays. In tight inner loops or other performance critical situations, you may wish to skip these bounds checks to improve runtime performance. For instance, in order to emit vectorized (SIMD) instructions, your loop body cannot contain branches, and thus cannot contain bounds checks. Consequently, Julia includes an <code>@inbounds(...)</code> macro to tell the compiler to skip such bounds checks within the given block. For the built-in <code>Array</code> type, the magic happens inside the <code>arrayref</code> and <code>arrayset</code> intrinsics. User-defined array types instead use the <code>@boundscheck(...)</code> macro to achieve context-sensitive code selection.</p><h2><a class="nav-anchor" id="Eliding-bounds-checks-1" href="#Eliding-bounds-checks-1">Eliding bounds checks</a></h2><p>The <code>@boundscheck(...)</code> macro marks blocks of code that perform bounds checking. When such blocks appear inside of an <code>@inbounds(...)</code> block, the compiler removes these blocks. When the <code>@boundscheck(...)</code> is nested inside of a calling function containing an <code>@inbounds(...)</code>, the compiler will remove the <code>@boundscheck</code> block <em>only if it is inlined</em> into the calling function. For example, you might write the method <code>sum</code> as:</p><pre><code class="language-julia">function sum(A::AbstractArray)
|
|
r = zero(eltype(A))
|
|
for i = 1:length(A)
|
|
@inbounds r += A[i]
|
|
end
|
|
return r
|
|
end</code></pre><p>With a custom array-like type <code>MyArray</code> having:</p><pre><code class="language-julia">@inline getindex(A::MyArray, i::Real) = (@boundscheck checkbounds(A,i); A.data[to_index(i)])</code></pre><p>Then when <code>getindex</code> is inlined into <code>sum</code>, the call to <code>checkbounds(A,i)</code> will be elided. If your function contains multiple layers of inlining, only <code>@boundscheck</code> blocks at most one level of inlining deeper are eliminated. The rule prevents unintended changes in program behavior from code further up the stack.</p><h2><a class="nav-anchor" id="Propagating-inbounds-1" href="#Propagating-inbounds-1">Propagating inbounds</a></h2><p>There may be certain scenarios where for code-organization reasons you want more than one layer between the <code>@inbounds</code> and <code>@boundscheck</code> declarations. For instance, the default <code>getindex</code> methods have the chain <code>getindex(A::AbstractArray, i::Real)</code> calls <code>getindex(IndexStyle(A), A, i)</code> calls <code>_getindex(::IndexLinear, A, i)</code>.</p><p>To override the "one layer of inlining" rule, a function may be marked with <code>@propagate_inbounds</code> to propagate an inbounds context (or out of bounds context) through one additional layer of inlining.</p><h2><a class="nav-anchor" id="The-bounds-checking-call-hierarchy-1" href="#The-bounds-checking-call-hierarchy-1">The bounds checking call hierarchy</a></h2><p>The overall hierarchy is:</p><ul><li><p><code>checkbounds(A, I...)</code> which calls</p><ul><li><p><code>checkbounds(Bool, A, I...)</code> which calls</p><ul><li><p><code>checkbounds_indices(Bool, indices(A), I)</code> which recursively calls</p><ul><li><p><code>checkindex</code> for each dimension</p></li></ul></li></ul></li></ul></li></ul><p>Here <code>A</code> is the array, and <code>I</code> contains the "requested" indices. <code>indices(A)</code> returns a tuple of "permitted" indices of <code>A</code>.</p><p><code>checkbounds(A, I...)</code> throws an error if the indices are invalid, whereas <code>checkbounds(Bool, A, I...)</code> returns <code>false</code> in that circumstance. <code>checkbounds_indices</code> discards any information about the array other than its <code>indices</code> tuple, and performs a pure indices-vs-indices comparison: this allows relatively few compiled methods to serve a huge variety of array types. Indices are specified as tuples, and are usually compared in a 1-1 fashion with individual dimensions handled by calling another important function, <code>checkindex</code>: typically,</p><pre><code class="language-julia">checkbounds_indices(Bool, (IA1, IA...), (I1, I...)) = checkindex(Bool, IA1, I1) &
|
|
checkbounds_indices(Bool, IA, I)</code></pre><p>so <code>checkindex</code> checks a single dimension. All of these functions, including the unexported <code>checkbounds_indices</code> have docstrings accessible with <code>?</code> .</p><p>If you have to customize bounds checking for a specific array type, you should specialize <code>checkbounds(Bool, A, I...)</code>. However, in most cases you should be able to rely on <code>checkbounds_indices</code> as long as you supply useful <code>indices</code> for your array type.</p><p>If you have novel index types, first consider specializing <code>checkindex</code>, which handles a single index for a particular dimension of an array. If you have a custom multidimensional index type (similar to <code>CartesianIndex</code>), then you may have to consider specializing <code>checkbounds_indices</code>.</p><p>Note this hierarchy has been designed to reduce the likelihood of method ambiguities. We try to make <code>checkbounds</code> the place to specialize on array type, and try to avoid specializations on index types; conversely, <code>checkindex</code> is intended to be specialized only on index type (especially, the last argument).</p><footer><hr/><a class="previous" href="stdio.html"><span class="direction">Previous</span><span class="title">printf() and stdio in the Julia runtime</span></a><a class="next" href="locks.html"><span class="direction">Next</span><span class="title">Proper maintenance and care of multi-threading locks</span></a></footer></article></body></html>
|