File: //usr/share/gtk-doc/html/glib/glib-Atomically-reference-counted-data.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Atomically reference counted data: GLib Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="GLib Reference Manual">
<link rel="up" href="glib-data-types.html" title="GLib Data Types">
<link rel="prev" href="glib-Reference-counted-data.html" title="Reference counted data">
<link rel="next" href="glib-Reference-counted-strings.html" title="Reference counted strings">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span>
<a href="#glib-Atomically-reference-counted-data.description" class="shortcut">Description</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="glib-Reference-counted-data.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="glib-Reference-counted-strings.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="glib-Atomically-reference-counted-data"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="glib-Atomically-reference-counted-data.top_of_page"></a>Atomically reference counted data</span></h2>
<p>Atomically reference counted data — Allocated memory with atomic reference counting semantics</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="glib-Atomically-reference-counted-data.functions"></a><h2>Functions</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="functions_proto_type">
<col class="functions_proto_name">
</colgroup>
<tbody>
<tr>
<td class="function_type">
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>
</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-alloc" title="g_atomic_rc_box_alloc ()">g_atomic_rc_box_alloc</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>
</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-alloc0" title="g_atomic_rc_box_alloc0 ()">g_atomic_rc_box_alloc0</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="define_keyword">#define</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-new" title="g_atomic_rc_box_new()">g_atomic_rc_box_new</a><span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="define_keyword">#define</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-new0" title="g_atomic_rc_box_new0()">g_atomic_rc_box_new0</a><span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>
</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-dup" title="g_atomic_rc_box_dup ()">g_atomic_rc_box_dup</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>
</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-acquire" title="g_atomic_rc_box_acquire ()">g_atomic_rc_box_acquire</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-release" title="g_atomic_rc_box_release ()">g_atomic_rc_box_release</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-release-full" title="g_atomic_rc_box_release_full ()">g_atomic_rc_box_release_full</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>
</td>
<td class="function_name">
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-get-size" title="g_atomic_rc_box_get_size ()">g_atomic_rc_box_get_size</a> <span class="c_punctuation">()</span>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="glib-Atomically-reference-counted-data.includes"></a><h2>Includes</h2>
<pre class="synopsis">#include <glib.h>
#include <glib/gi18n.h>
</pre>
</div>
<div class="refsect1">
<a name="glib-Atomically-reference-counted-data.description"></a><h2>Description</h2>
<p>An "atomically reference counted box", or "ArcBox", is an opaque wrapper
data type that is guaranteed to be as big as the size of a given data type,
and which augments the given data type with thread safe reference counting
semantics for its memory management.</p>
<p>ArcBox is useful if you have a plain old data type, like a structure
typically placed on the stack, and you wish to provide additional API
to use it on the heap; or if you want to implement a new type to be
passed around by reference without necessarily implementing copy/free
semantics or your own reference counting.</p>
<p>The typical use is:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">name</span><span class="p">;</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">address</span><span class="p">;</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">city</span><span class="p">;</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">state</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">age</span><span class="p">;</span>
<span class="p">}</span> <span class="n">Person</span><span class="p">;</span>
<span class="n">Person</span> <span class="o">*</span>
<span class="nf">person_new</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">return</span> <span class="n">g_atomic_rc_box_new0</span> <span class="p">(</span><span class="n">Person</span><span class="p">);</span>
<span class="p">}</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p></p>
<p>Every time you wish to acquire a reference on the memory, you should
call <a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-acquire" title="g_atomic_rc_box_acquire ()"><code class="function">g_atomic_rc_box_acquire()</code></a>; similarly, when you wish to release a reference
you should call <a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-release" title="g_atomic_rc_box_release ()"><code class="function">g_atomic_rc_box_release()</code></a>:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="c1">// Add a Person to the Database; the Database acquires ownership</span>
<span class="c1">// of the Person instance</span>
<span class="kt">void</span>
<span class="nf">add_person_to_database</span> <span class="p">(</span><span class="n">Database</span> <span class="o">*</span><span class="n">db</span><span class="p">,</span> <span class="n">Person</span> <span class="o">*</span><span class="n">p</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">db</span><span class="o">-></span><span class="n">persons</span> <span class="o">=</span> <span class="n">g_list_prepend</span> <span class="p">(</span><span class="n">db</span><span class="o">-></span><span class="n">persons</span><span class="p">,</span> <span class="n">g_atomic_rc_box_acquire</span> <span class="p">(</span><span class="n">p</span><span class="p">));</span>
<span class="p">}</span>
<span class="c1">// Removes a Person from the Database; the reference acquired by</span>
<span class="c1">// add_person_to_database() is released here</span>
<span class="kt">void</span>
<span class="nf">remove_person_from_database</span> <span class="p">(</span><span class="n">Database</span> <span class="o">*</span><span class="n">db</span><span class="p">,</span> <span class="n">Person</span> <span class="o">*</span><span class="n">p</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">db</span><span class="o">-></span><span class="n">persons</span> <span class="o">=</span> <span class="n">g_list_remove</span> <span class="p">(</span><span class="n">db</span><span class="o">-></span><span class="n">persons</span><span class="p">,</span> <span class="n">p</span><span class="p">);</span>
<span class="n">g_atomic_rc_box_release</span> <span class="p">(</span><span class="n">p</span><span class="p">);</span>
<span class="p">}</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p></p>
<p>If you have additional memory allocated inside the structure, you can
use <a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-release-full" title="g_atomic_rc_box_release_full ()"><code class="function">g_atomic_rc_box_release_full()</code></a>, which takes a function pointer, which
will be called if the reference released was the last:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="kt">void</span>
<span class="nf">person_clear</span> <span class="p">(</span><span class="n">Person</span> <span class="o">*</span><span class="n">p</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">g_free</span> <span class="p">(</span><span class="n">p</span><span class="o">-></span><span class="n">name</span><span class="p">);</span>
<span class="n">g_free</span> <span class="p">(</span><span class="n">p</span><span class="o">-></span><span class="n">address</span><span class="p">);</span>
<span class="n">g_free</span> <span class="p">(</span><span class="n">p</span><span class="o">-></span><span class="n">city</span><span class="p">);</span>
<span class="n">g_free</span> <span class="p">(</span><span class="n">p</span><span class="o">-></span><span class="n">state</span><span class="p">);</span>
<span class="p">}</span>
<span class="kt">void</span>
<span class="nf">remove_person_from_database</span> <span class="p">(</span><span class="n">Database</span> <span class="o">*</span><span class="n">db</span><span class="p">,</span> <span class="n">Person</span> <span class="o">*</span><span class="n">p</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">db</span><span class="o">-></span><span class="n">persons</span> <span class="o">=</span> <span class="n">g_list_remove</span> <span class="p">(</span><span class="n">db</span><span class="o">-></span><span class="n">persons</span><span class="p">,</span> <span class="n">p</span><span class="p">);</span>
<span class="n">g_atomic_rc_box_release_full</span> <span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="p">(</span><span class="n">GDestroyNotify</span><span class="p">)</span> <span class="n">person_clear</span><span class="p">);</span>
<span class="p">}</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p></p>
<p>If you wish to transfer the ownership of a reference counted data
type without increasing the reference count, you can use <a class="link" href="glib-Memory-Allocation.html#g-steal-pointer" title="g_steal_pointer ()"><code class="function">g_steal_pointer()</code></a>:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="n">Person</span> <span class="o">*</span><span class="n">p</span> <span class="o">=</span> <span class="n">g_atomic_rc_box_new</span> <span class="p">(</span><span class="n">Person</span><span class="p">);</span>
<span class="n">fill_person_details</span> <span class="p">(</span><span class="n">p</span><span class="p">);</span>
<span class="n">add_person_to_database</span> <span class="p">(</span><span class="n">db</span><span class="p">,</span> <span class="n">g_steal_pointer</span> <span class="p">(</span><span class="o">&</span><span class="n">p</span><span class="p">));</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p></p>
<div class="refsect3">
<a name="id-1.6.24.5.16"></a><h4>Thread safety</h4>
<p>The reference counting operations on data allocated using <a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-alloc" title="g_atomic_rc_box_alloc ()"><code class="function">g_atomic_rc_box_alloc()</code></a>,
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-new" title="g_atomic_rc_box_new()"><code class="function">g_atomic_rc_box_new()</code></a>, and <a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-dup" title="g_atomic_rc_box_dup ()"><code class="function">g_atomic_rc_box_dup()</code></a> are guaranteed to be atomic, and thus
can be safely be performed by different threads. It is important to note that
only the reference acquisition and release are atomic; changes to the content
of the data are your responsibility.</p>
</div>
<div class="refsect3">
<a name="id-1.6.24.5.17"></a><h4>Automatic pointer clean up</h4>
<p>If you want to add <a class="link" href="glib-Miscellaneous-Macros.html#g-autoptr" title="g_autoptr()"><code class="function">g_autoptr()</code></a> support to your plain old data type through
reference counting, you can use the <a class="link" href="glib-Miscellaneous-Macros.html#G-DEFINE-AUTOPTR-CLEANUP-FUNC:CAPS" title="G_DEFINE_AUTOPTR_CLEANUP_FUNC()"><code class="function">G_DEFINE_AUTOPTR_CLEANUP_FUNC()</code></a> and
<a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-release" title="g_atomic_rc_box_release ()"><code class="function">g_atomic_rc_box_release()</code></a>:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="n">G_DEFINE_AUTOPTR_CLEANUP_FUNC</span> <span class="p">(</span><span class="n">MyDataStruct</span><span class="p">,</span> <span class="n">g_atomic_rc_box_release</span><span class="p">)</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p></p>
<p>If you need to clear the contents of the data, you will need to use an
ancillary function that calls <a class="link" href="glib-Reference-counted-data.html#g-rc-box-release-full" title="g_rc_box_release_full ()"><code class="function">g_rc_box_release_full()</code></a>:</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="k">static</span> <span class="kt">void</span>
<span class="nf">my_data_struct_release</span> <span class="p">(</span><span class="n">MyDataStruct</span> <span class="o">*</span><span class="n">data</span><span class="p">)</span>
<span class="p">{</span>
<span class="c1">// my_data_struct_clear() is defined elsewhere</span>
<span class="n">g_atomic_rc_box_release_full</span> <span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="p">(</span><span class="n">GDestroyNotify</span><span class="p">)</span> <span class="n">my_data_struct_clear</span><span class="p">);</span>
<span class="p">}</span>
<span class="n">G_DEFINE_AUTOPTR_CLEANUP_FUNC</span> <span class="p">(</span><span class="n">MyDataStruct</span><span class="p">,</span> <span class="n">my_data_struct_release</span><span class="p">)</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p></p>
</div>
</div>
<div class="refsect1">
<a name="glib-Atomically-reference-counted-data.functions_details"></a><h2>Functions</h2>
<div class="refsect2">
<a name="g-atomic-rc-box-alloc"></a><h3>g_atomic_rc_box_alloc ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>
g_atomic_rc_box_alloc (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> block_size</code></em>);</pre>
<p>Allocates <em class="parameter"><code>block_size</code></em>
bytes of memory, and adds atomic
reference counting semantics to it.</p>
<p>The data will be freed when its reference count drops to
zero.</p>
<p>The allocated data is guaranteed to be suitably aligned for any
built-in type.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-alloc.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description"><p>the size of the allocation, must be greater than 0</p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="g-atomic-rc-box-alloc.returns"></a><h4>Returns</h4>
<p>a pointer to the allocated memory. </p>
<p><span class="annotation">[<acronym title="The caller owns the data, and is responsible for free it."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
<hr>
<div class="refsect2">
<a name="g-atomic-rc-box-alloc0"></a><h3>g_atomic_rc_box_alloc0 ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>
g_atomic_rc_box_alloc0 (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> block_size</code></em>);</pre>
<p>Allocates <em class="parameter"><code>block_size</code></em>
bytes of memory, and adds atomic
reference counting semantics to it.</p>
<p>The contents of the returned data is set to zero.</p>
<p>The data will be freed when its reference count drops to
zero.</p>
<p>The allocated data is guaranteed to be suitably aligned for any
built-in type.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-alloc0.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description"><p>the size of the allocation, must be greater than 0</p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="g-atomic-rc-box-alloc0.returns"></a><h4>Returns</h4>
<p>a pointer to the allocated memory. </p>
<p><span class="annotation">[<acronym title="The caller owns the data, and is responsible for free it."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
<hr>
<div class="refsect2">
<a name="g-atomic-rc-box-new"></a><h3>g_atomic_rc_box_new()</h3>
<pre class="programlisting">#define g_atomic_rc_box_new(type)</pre>
<p>A convenience macro to allocate atomically reference counted
data with the size of the given <em class="parameter"><code>type</code></em>
.</p>
<p>This macro calls <a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-alloc" title="g_atomic_rc_box_alloc ()"><code class="function">g_atomic_rc_box_alloc()</code></a> with <code class="literal">sizeof (@type)</code> and
casts the returned pointer to a pointer of the given <em class="parameter"><code>type</code></em>
,
avoiding a type cast in the source code.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-new.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>type</p></td>
<td class="parameter_description"><p>the type to allocate, typically a structure name</p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="g-atomic-rc-box-new.returns"></a><h4>Returns</h4>
<p>a pointer to the allocated
memory, cast to a pointer for the given <em class="parameter"><code>type</code></em>
. </p>
<p><span class="annotation">[<acronym title="The caller owns the data, and is responsible for free it."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
<hr>
<div class="refsect2">
<a name="g-atomic-rc-box-new0"></a><h3>g_atomic_rc_box_new0()</h3>
<pre class="programlisting">#define g_atomic_rc_box_new0(type)</pre>
<p>A convenience macro to allocate atomically reference counted
data with the size of the given <em class="parameter"><code>type</code></em>
, and set its contents
to zero.</p>
<p>This macro calls <a class="link" href="glib-Atomically-reference-counted-data.html#g-atomic-rc-box-alloc0" title="g_atomic_rc_box_alloc0 ()"><code class="function">g_atomic_rc_box_alloc0()</code></a> with <code class="literal">sizeof (@type)</code> and
casts the returned pointer to a pointer of the given <em class="parameter"><code>type</code></em>
,
avoiding a type cast in the source code.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-new0.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>type</p></td>
<td class="parameter_description"><p>the type to allocate, typically a structure name</p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="g-atomic-rc-box-new0.returns"></a><h4>Returns</h4>
<p>a pointer to the allocated
memory, cast to a pointer for the given <em class="parameter"><code>type</code></em>
. </p>
<p><span class="annotation">[<acronym title="The caller owns the data, and is responsible for free it."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
<hr>
<div class="refsect2">
<a name="g-atomic-rc-box-dup"></a><h3>g_atomic_rc_box_dup ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>
g_atomic_rc_box_dup (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> block_size</code></em>,
<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> mem_block</code></em>);</pre>
<p>Allocates a new block of data with atomic reference counting
semantics, and copies <em class="parameter"><code>block_size</code></em>
bytes of <em class="parameter"><code>mem_block</code></em>
into it.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-dup.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>block_size</p></td>
<td class="parameter_description"><p>the number of bytes to copy, must be greater than 0</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description"><p>the memory to copy. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="g-atomic-rc-box-dup.returns"></a><h4>Returns</h4>
<p>a pointer to the allocated
memory. </p>
<p><span class="annotation">[<acronym title="The caller owns the data, and is responsible for free it."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
<hr>
<div class="refsect2">
<a name="g-atomic-rc-box-acquire"></a><h3>g_atomic_rc_box_acquire ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>
g_atomic_rc_box_acquire (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> mem_block</code></em>);</pre>
<p>Atomically acquires a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>
.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-acquire.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description"><p>a pointer to reference counted data. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="g-atomic-rc-box-acquire.returns"></a><h4>Returns</h4>
<p>a pointer to the data,
with its reference count increased. </p>
<p><span class="annotation">[<acronym title="The caller owns the data, and is responsible for free it."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
<hr>
<div class="refsect2">
<a name="g-atomic-rc-box-release"></a><h3>g_atomic_rc_box_release ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
g_atomic_rc_box_release (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> mem_block</code></em>);</pre>
<p>Atomically releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>
.</p>
<p>If the reference was the last one, it will free the
resources allocated for <em class="parameter"><code>mem_block</code></em>
.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-release.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description"><p>a pointer to reference counted data. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="The caller owns the data, and is responsible for free it."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></td>
</tr></tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
<hr>
<div class="refsect2">
<a name="g-atomic-rc-box-release-full"></a><h3>g_atomic_rc_box_release_full ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
g_atomic_rc_box_release_full (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> mem_block</code></em>,
<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> clear_func</code></em>);</pre>
<p>Atomically releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>
.</p>
<p>If the reference was the last one, it will call <em class="parameter"><code>clear_func</code></em>
to clear the contents of <em class="parameter"><code>mem_block</code></em>
, and then will free the
resources allocated for <em class="parameter"><code>mem_block</code></em>
.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-release-full.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description"><p>a pointer to reference counted data. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="The caller owns the data, and is responsible for free it."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></td>
</tr>
<tr>
<td class="parameter_name"><p>clear_func</p></td>
<td class="parameter_description"><p>a function to call when clearing the data. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
<hr>
<div class="refsect2">
<a name="g-atomic-rc-box-get-size"></a><h3>g_atomic_rc_box_get_size ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>
g_atomic_rc_box_get_size (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> mem_block</code></em>);</pre>
<p>Retrieves the size of the reference counted data pointed by <em class="parameter"><code>mem_block</code></em>
.</p>
<div class="refsect3">
<a name="g-atomic-rc-box-get-size.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>mem_block</p></td>
<td class="parameter_description"><p>a pointer to reference counted data. </p></td>
<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL must not be passed as the value in, out, in-out; or as a return value."><span class="acronym">not nullable</span></acronym>]</span></td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="g-atomic-rc-box-get-size.returns"></a><h4>Returns</h4>
<p> the size of the data, in bytes</p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>