stralloc.html (4855B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the stralloc library interface</title> 7 <meta name="Description" content="skalibs: the stralloc library interface" /> 8 <meta name="Keywords" content="skalibs c unix stralloc library libstddjb" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>stralloc</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/stralloc.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>stralloc</tt> is the preferred skalibs way of storing objects into 32 heap memory. It focuses on strings of <em>char</em>, which is the generic 33 way to handle any object. For easy structure manipulation, the 34 <a href="genalloc.html">genalloc</a> 35 series of functions can be used; those functions are mostly macros wrapping 36 calls to their stralloc counterparts. 37 </p> 38 39 <p> 40 A stralloc is a structure containing the following fields: 41 </p> 42 43 <ul> 44 <li> <em>s</em>: a pointer to a zone of heap memory. The stralloc 45 functions internally manipulate those via the 46 <a href="alloc.html">alloc</a> series of functions. It is recommended 47 to never modify that field manually. </li> 48 <li> <em>len</em>: the <strong>used</strong> length of the 49 allocated zone. It is the only field that the user can modify 50 directly. </li> 51 <li> <em>a</em>: the number of allocated bytes. The user should never 52 have to access that field, because the memory allocation management 53 should be entirely transparent. <em>len</em> cannot exceed <em>a</em>: 54 if an operation needs a bigger <em>len</em>, it will automatically 55 reallocate as needed. </li> 56 </ul> 57 58 <p> 59 The benefits of using stralloc are as follows: 60 </p> 61 62 <ul> 63 <li> Memory allocation is performed on-demand and automatically, with 64 a suitable size. Heuristics are used to accommodate constantly growing 65 strings while minimizing the amount of needed reallocations. </li> 66 <li> If every heap-allocated object is represented by a stralloc, then 67 it is very easy to identify what pointer is in the heap. When you stop 68 using a pointer <em>p</em>, should you free it ? Sometimes it's not 69 easy to find out. When you stop using a stralloc <em>sa</em>, you 70 <em>know</em> you must call <tt>stralloc_free(&sa)</tt>. Store 71 your strong references as strallocs and weak references as simple 72 pointers, and never free simple pointers. This policy allows me to 73 boast that <em>no skarnet.org software has ever leaked memory</em>. </li> 74 <li> Repeated for emphasis: 75 <strong> the golden rule for programming with strallocs is 76 <em>every pointer to the heap must be owned by a stralloc</em>. </strong> 77 Every pointer you handle yourself either does not point to the heap, 78 or is weak. That sometimes implies unusual programming practices, such 79 as having storage separated from structure, but it's hands down the 80 easiest way to keep control of your heap in complex situations. </li> 81 <li> The indirection layer makes weak references immune to 82 reallocation troubles. The <em>s</em> field may change when a 83 reallocation happens, but the stralloc structure's address never 84 changes. </li> 85 </ul> 86 87 <p> 88 A stralloc can be declared anywhere: static/global data, stack or heap. (Of course, 89 as a general rule, you should favor the stack whenever possible.) 90 A stralloc should be initialized to STRALLOC_ZERO before its first use. 91 </p> 92 93 <h2> Functions </h2> 94 95 <p> 96 <code> int stralloc_catb (stralloc *sa, char const *s, size_t len) </code> <br /> 97 Appends the <em>len</em> bytes pointed to by <em>s</em> to the end of the 98 memory zone handled by *<em>sa</em>, automatically allocating more memory 99 if needed. Returns 1 if it succeeds, and 0 if it fails. 100 </p> 101 102 <p> 103 <code> void stralloc_free (stralloc *sa) </code> <br /> 104 Frees <em>*sa</em>, i.e. calls <a href="alloc.html">alloc_free</a> 105 on <em>sa</em>→s then zeroes the structure. *<em>sa</em> is 106 then reusable. However, it is not good practice to call this function 107 if you're going to reuse *<em>sa</em> soon: it takes time and causes 108 memory fragmentation. Just setting <em>sa</em>→len to 0 allows 109 you to instantly reuse the allocated block of memory. 110 </p> 111 112 <p> 113 The above are the most important and fundamental functions of 114 <tt>skalibs/stralloc.h</tt>. Other functions can be found in this header and 115 their prototypes are self-explaining. 116 </p> 117 118 </body> 119 </html>