|
|
@@ -0,0 +1,107 @@
|
|
|
+<!DOCTYPE html> <HTML lang=en> <HEAD> <STYLE>
|
|
|
+body { background-color: #EEFFEE; font-size: 1.0rem; font-family: Arial; max-width: 60rem;
|
|
|
+ color: #000000; margin: 0px;
|
|
|
+ padding-left: 0px; padding-right: 0px; padding-top: 0px; padding-bottom: 0px; }
|
|
|
+H1 { padding-left: 10px; padding-right: 0px; padding-top: 10px; padding-bottom: 10px; font-size: 1.4rem; }
|
|
|
+H2 { padding-left: 10px; padding-right: 0px; padding-top: 10px; padding-bottom: 0px; font-size: 1.2rem; }
|
|
|
+blockquote {
|
|
|
+ tab-size: 3rem;
|
|
|
+ color: #88FF88; background: #000000;
|
|
|
+ font-size: 0.95rem; font-family: monospace;
|
|
|
+ padding-left: 5px; padding-right: 5px;
|
|
|
+ padding-top: 5px; padding-bottom: 5px;
|
|
|
+}
|
|
|
+P { padding-left: 20px; padding-right: 0px; padding-top: 0px; padding-bottom: 0px; }
|
|
|
+IMG { padding-left: 0px; padding-right: 0px; padding-top: 2px; padding-bottom: 0px;
|
|
|
+ max-width: 100%; }
|
|
|
+A { display: inline; border-radius: 4px;
|
|
|
+ font-size: 1.0rem; font-family: Arial; color: #000044; text-decoration: none;
|
|
|
+ padding-left: 4px; padding-right: 4px; padding-top: 4px; padding-bottom: 4px; }
|
|
|
+A:hover { color: #FFFF00; background: #000044; }
|
|
|
+A:active { color: #FFFFFF; background: #444444; }
|
|
|
+</STYLE> </HEAD> <BODY>
|
|
|
+<IMG SRC="Images/Title.png" ALT="Images/Title.png">
|
|
|
+<P>
|
|
|
+<A href="Manual.html">Back to main page</A>
|
|
|
+</P><P>
|
|
|
+</P><H1> Choosing storage</H1><P>
|
|
|
+</P><P>
|
|
|
+The terms "safe" and "unsafe" are relative to the context.
|
|
|
+A low level pointer is considered safe from having bound checks in debug mode, because it is supposed to be bruteforce tested in debug mode to catch all bugs.
|
|
|
+A high level collection is considered unsafe if it does not have bound checks in release mode, because collections are used for more complex control flow where bruteforce testing might not be enough.
|
|
|
+
|
|
|
+</P><P>
|
|
|
+</P><IMG SRC="Images/Border.png"><P>
|
|
|
+</P><H2> Buffer and SafePointer</H2><P>
|
|
|
+</P><P>
|
|
|
+<IMG SRC="Images/SmallDot.png">
|
|
|
+Source/DFPSR/api/bufferAPI.h
|
|
|
+
|
|
|
+</P><P>
|
|
|
+<IMG SRC="Images/SmallDot.png">
|
|
|
+Source/DFPSR/base/SafePointer.h
|
|
|
+
|
|
|
+</P><P>
|
|
|
+The fastest way to access data is to use Buffer and SafePointer.
|
|
|
+Buffer replaces raw memory allocations, is responsible for ownership using automatic reference counting, and is padded and aligned for SIMD vectorization by default.
|
|
|
+SafePointer replaces raw pointers with zero overhead in release mode and safety checks in debug mode.
|
|
|
+
|
|
|
+</P><P>
|
|
|
+<IMG SRC="Images/Warning.png" ALT="Warning">
|
|
|
+While Buffer aligns the start for you, it does not know which data types you are storing inside of it.
|
|
|
+Make sure that the innermost types (such as integers and floats) are aligned by their own size to ensure good performance and avoid crashes on certain processors that do not support unaligned access.
|
|
|
+
|
|
|
+</P><P>
|
|
|
+</P><IMG SRC="Images/Border.png"><P>
|
|
|
+</P><H2> FixedArray</H2><P>
|
|
|
+</P><P>
|
|
|
+<IMG SRC="Images/SmallDot.png">
|
|
|
+Source/DFPSR/collection/FixedArray
|
|
|
+
|
|
|
+</P><P>
|
|
|
+For small fixed size allocations, FixedArray is the simplest of all collections by allocating all data directly in the head without pointing anywhere else in the memory.
|
|
|
+The [] operator is bound checked by default in release mode, but if you only want bound checks in debug mode, you can call unsafe_readAccess or unsafe_writeAccess instead.
|
|
|
+
|
|
|
+</P><P>
|
|
|
+</P><IMG SRC="Images/Border.png"><P>
|
|
|
+</P><H2> Array</H2><P>
|
|
|
+</P><P>
|
|
|
+<IMG SRC="Images/SmallDot.png">
|
|
|
+Source/DFPSR/collection/Array
|
|
|
+
|
|
|
+</P><P>
|
|
|
+When you know the size to allocate ahead of time but it is large or you do not know it in compile time, Array allows dynamically allocating the data.
|
|
|
+The [] operator is bound checked by default in release mode, but if you only want bound checks in debug mode, you can call unsafe_readAccess or unsafe_writeAccess instead.
|
|
|
+To change the size, assign a new array in its place constructed with different dimensions.
|
|
|
+
|
|
|
+</P><P>
|
|
|
+</P><IMG SRC="Images/Border.png"><P>
|
|
|
+</P><H2> Field</H2><P>
|
|
|
+</P><P>
|
|
|
+<IMG SRC="Images/SmallDot.png">
|
|
|
+Source/DFPSR/collection/Field
|
|
|
+
|
|
|
+</P><P>
|
|
|
+Field is a slow but convenient wrapper around Array that simplifies two-dimensional storage.
|
|
|
+Rows are not padded, which preserves memory but makes access slower.
|
|
|
+Ideal for reference implementations, quick prototypes and things that will not become a performance bottleneck.
|
|
|
+If you only need to store unsigned integers or floats, consider using multiple images instead, for easy visualization of results.
|
|
|
+
|
|
|
+</P><P>
|
|
|
+</P><IMG SRC="Images/Border.png"><P>
|
|
|
+</P><H2> List</H2><P>
|
|
|
+</P><P>
|
|
|
+<IMG SRC="Images/SmallDot.png">
|
|
|
+Source/DFPSR/collection/List
|
|
|
+
|
|
|
+</P><P>
|
|
|
+List is an array based list with continuous memory.
|
|
|
+The [] operator is always bound checked.
|
|
|
+
|
|
|
+</P><P>
|
|
|
+<IMG SRC="Images/Warning.png" ALT="Warning">
|
|
|
+Reserving memory or adding elements to List may cause reallocation of the buffer, which may invalidate any pointers and references to the data.
|
|
|
+Never change the size of a list while iterating over the elements using pointers.
|
|
|
+Deleting elements from List should be done by looping backwards by index, so that the loop is always entering regions not affected by element removal.
|
|
|
+</P>
|
|
|
+</BODY> </HTML>
|
David Piuva