summaryrefslogtreecommitdiffstats
path: root/apidoc/group___memory.html
diff options
authordodji <dodji>2022-10-02 16:34:29 +0000
committerdodji <dodji>2022-10-02 16:34:29 +0000
commit2bb2964a54338a876a6a6176ae838a795422e48e (patch)
tree84a0347d1b2f22dc76bf8e96e47484f28df9df57 /apidoc/group___memory.html
parentUpdate website for 2.1 (diff)
Update api doc for 2.1
Diffstat (limited to 'apidoc/group___memory.html')
-rw-r--r--apidoc/group___memory.html105
1 files changed, 48 insertions, 57 deletions
diff --git a/apidoc/group___memory.html b/apidoc/group___memory.html
index 347e3bb8..2b963387 100644
--- a/apidoc/group___memory.html
+++ b/apidoc/group___memory.html
@@ -1,18 +1,17 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml"> 2<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
3<head> 3<head>
4<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 4<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5<meta http-equiv="X-UA-Compatible" content="IE=9"/> 5<meta http-equiv="X-UA-Compatible" content="IE=11"/>
6<meta name="generator" content="Doxygen 1.8.5"/> 6<meta name="generator" content="Doxygen 1.9.5"/>
7<meta name="viewport" content="width=device-width, initial-scale=1"/>
7<title>libabigail: Memory management</title> 8<title>libabigail: Memory management</title>
8<link href="tabs.css" rel="stylesheet" type="text/css"/> 9<link href="tabs.css" rel="stylesheet" type="text/css"/>
9<script type="text/javascript" src="jquery.js"></script> 10<script type="text/javascript" src="jquery.js"></script>
10<script type="text/javascript" src="dynsections.js"></script> 11<script type="text/javascript" src="dynsections.js"></script>
11<link href="search/search.css" rel="stylesheet" type="text/css"/> 12<link href="search/search.css" rel="stylesheet" type="text/css"/>
13<script type="text/javascript" src="search/searchdata.js"></script>
12<script type="text/javascript" src="search/search.js"></script> 14<script type="text/javascript" src="search/search.js"></script>
13<script type="text/javascript">
14 $(document).ready(function() { searchBox.OnSelectItem(0); });
15</script>
16<link href="doxygen.css" rel="stylesheet" type="text/css" /> 15<link href="doxygen.css" rel="stylesheet" type="text/css" />
17</head> 16</head>
18<body> 17<body>
@@ -20,8 +19,8 @@
20<div id="titlearea"> 19<div id="titlearea">
21<table cellspacing="0" cellpadding="0"> 20<table cellspacing="0" cellpadding="0">
22 <tbody> 21 <tbody>
23 <tr style="height: 56px;"> 22 <tr id="projectrow">
24 <td style="padding-left: 0.5em;"> 23 <td id="projectalign">
25 <div id="projectname">libabigail 24 <div id="projectname">libabigail
26 </div> 25 </div>
27 </td> 26 </td>
@@ -30,75 +29,67 @@
30</table> 29</table>
31</div> 30</div>
32<!-- end header part --> 31<!-- end header part -->
33<!-- Generated by Doxygen 1.8.5 --> 32<!-- Generated by Doxygen 1.9.5 -->
33<script type="text/javascript">
34/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
35var searchBox = new SearchBox("searchBox", "search/",'.html');
36/* @license-end */
37</script>
38<script type="text/javascript" src="menudata.js"></script>
39<script type="text/javascript" src="menu.js"></script>
34<script type="text/javascript"> 40<script type="text/javascript">
35var searchBox = new SearchBox("searchBox", "search",false,'Search'); 41/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
42$(function() {
43 initMenu('',true,false,'search.php','Search');
44 $(document).ready(function() { init_search(); });
45});
46/* @license-end */
36</script> 47</script>
37 <div id="navrow1" class="tabs"> 48<div id="main-nav"></div>
38 <ul class="tablist">
39 <li><a href="index.html"><span>Main&#160;Page</span></a></li>
40 <li><a href="modules.html"><span>Modules</span></a></li>
41 <li><a href="namespaces.html"><span>Namespaces</span></a></li>
42 <li><a href="annotated.html"><span>Classes</span></a></li>
43 <li><a href="files.html"><span>Files</span></a></li>
44 <li>
45 <div id="MSearchBox" class="MSearchBoxInactive">
46 <span class="left">
47 <img id="MSearchSelect" src="search/mag_sel.png"
48 onmouseover="return searchBox.OnSearchSelectShow()"
49 onmouseout="return searchBox.OnSearchSelectHide()"
50 alt=""/>
51 <input type="text" id="MSearchField" value="Search" accesskey="S"
52 onfocus="searchBox.OnSearchFieldFocus(true)"
53 onblur="searchBox.OnSearchFieldFocus(false)"
54 onkeyup="searchBox.OnSearchFieldChange(event)"/>
55 </span><span class="right">
56 <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
57 </span>
58 </div>
59 </li>
60 </ul>
61 </div>
62</div><!-- top --> 49</div><!-- top -->
63<!-- window showing the filter options --> 50<!-- window showing the filter options -->
64<div id="MSearchSelectWindow" 51<div id="MSearchSelectWindow"
65 onmouseover="return searchBox.OnSearchSelectShow()" 52 onmouseover="return searchBox.OnSearchSelectShow()"
66 onmouseout="return searchBox.OnSearchSelectHide()" 53 onmouseout="return searchBox.OnSearchSelectHide()"
67 onkeydown="return searchBox.OnSearchSelectKey(event)"> 54 onkeydown="return searchBox.OnSearchSelectKey(event)">
68<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(11)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(12)"><span class="SelectionMark">&#160;</span>Pages</a></div> 55</div>
69 56
70<!-- iframe showing the search results (closed by default) --> 57<!-- iframe showing the search results (closed by default) -->
71<div id="MSearchResultsWindow"> 58<div id="MSearchResultsWindow">
72<iframe src="javascript:void(0)" frameborder="0" 59<div id="MSearchResults">
73 name="MSearchResults" id="MSearchResults"> 60<div class="SRPage">
74</iframe> 61<div id="SRIndex">
62<div id="SRResults"></div>
63<div class="SRStatus" id="Loading">Loading...</div>
64<div class="SRStatus" id="Searching">Searching...</div>
65<div class="SRStatus" id="NoMatches">No Matches</div>
66</div>
67</div>
68</div>
75</div> 69</div>
76 70
77<div class="header"> 71<div class="header">
78 <div class="headertitle"> 72 <div class="headertitle"><div class="title">Memory management</div></div>
79<div class="title">Memory management</div> </div>
80</div><!--header--> 73</div><!--header-->
81<div class="contents"> 74<div class="contents">
82 75
83<p>How objects' lifetime is handled in libabigail. 76<p>How objects' lifetime is handled in libabigail.
84<a href="#details">More...</a></p> 77</p>
85<p>How objects' lifetime is handled in libabigail. </p> 78<p >How objects' lifetime is handled in libabigail. </p>
86<p>For memory management and garbage collection of libabigail's IR artifacts, we use std::shared_ptr and std::weak_ptr.</p> 79<p >For memory management and garbage collection of libabigail's IR artifacts, we use std::shared_ptr and std::weak_ptr.</p>
87<p>When manipulating these IR artifacts, there are a few rules to keep in mind.</p> 80<p >When manipulating these IR artifacts, there are a few rules to keep in mind.</p>
88<p><b>The declaration for a type is owned by only one scope </b></p> 81<p ><b>The declaration for a type is owned by only one scope </b></p>
89<p>This means that for each instance of abigail::type_base (a type) there is an instance of abigail::scope_decl that owns a abigail::decl_base_sptr (a shared pointer to an abigail::decl_base) that points to the declaration of that type. The abigail::type_base_sptr is added to the scope using the function <a class="el" href="namespaceabigail_1_1ir.html#aae1160145e2a416e690d5554794cf2b7" title="Appends a declaration to a given scope, if the declaration doesn&#39;t already belong to one...">abigail::add_decl_to_scope()</a>.</p> 82<p >This means that for each instance of abigail::type_base (a type) there is an instance of abigail::scope_decl that owns a abigail::decl_base_sptr (a shared pointer to an abigail::decl_base) that points to the declaration of that type. The abigail::type_base_sptr is added to the scope using the function <a class="el" href="namespaceabigail_1_1ir.html#aae1160145e2a416e690d5554794cf2b7" title="Appends a declaration to a given scope, if the declaration doesn&#39;t already belong to one.">abigail::add_decl_to_scope()</a>.</p>
90<p>There is a kind of type that is usually not syntactically owned by a scope: it's function type. In libabigail, function types are represented by abigail::function_type and abigail::method_type. These types must be owned by the translation unit they originate from. Adding them to the translation unit must be done by a call to the method function abigail::translation::bind_function_type_life_time().</p> 83<p >There is a kind of type that is usually not syntactically owned by a scope: it's function type. In libabigail, function types are represented by abigail::function_type and abigail::method_type. These types must be owned by the translation unit they originate from. Adding them to the translation unit must be done by a call to the method function abigail::translation::bind_function_type_life_time().</p>
91<p><b> A declaration that has a type does NOT own the type </b></p> 84<p ><b> A declaration that has a type does NOT own the type </b></p>
92<p>This means that, for instance, in an abigail::var_decl (a variable declaration), the type of the declaration is not owned by the declaration. In other (concrete) words, the variable declaration doesn't have a shared pointer to the type. Rather, it has a *weak* pointer to its type. That means that it has a data member of type abigail::type_base_wptr that contains the type of the declaration.</p> 85<p >This means that, for instance, in an abigail::var_decl (a variable declaration), the type of the declaration is not owned by the declaration. In other (concrete) words, the variable declaration doesn't have a shared pointer to the type. Rather, it has a *weak* pointer to its type. That means that it has a data member of type <a class="el" href="namespaceabigail_1_1ir.html#a2bb6fdde1e0c6f5c0725881bb8b0cbf6" title="Convenience typedef for a weak pointer on a type_base.">abigail::type_base_wptr</a> that contains the type of the declaration.</p>
93<p>But then <a class="el" href="classabigail_1_1ir_1_1var__decl.html#a15b0ae392e0041f7b24fed26926d10da" title="Getter of the type of the variable. ">abigail::var_decl::get_type()</a> returns a shared pointer that is constructed from the internal weak pointer to the type. That way, users of the type of the var can own a temporary reference on it and be assured that the type's life time is long enough for their need.</p> 86<p >But then abigail::var_decl::get_type() returns a shared pointer that is constructed from the internal weak pointer to the type. That way, users of the type of the var can own a temporary reference on it and be assured that the type's life time is long enough for their need.</p>
94<p>Likewise, data members, function and template parameters similarly have weak pointers on their type.</p> 87<p >Likewise, data members, function and template parameters similarly have weak pointers on their type.</p>
95<p>If, for a reason, you really need to keep a type alive for the entire lifetime of the type system, then you can bind the life time of that type to the life time of the environment that is supposed to outlive the type system. You do that by passing the type to the function <a class="el" href="namespaceabigail_1_1ir.html#aaa933feb1ee738ca0f64309d7d276e80" title="Make sure that the life time of a given (smart pointer to a) type is the same as the life time of the...">environment::keep_type_alive()</a>. </p> 88<p >If, for a reason, you really need to keep a type alive for the entire lifetime of the type system, then you can bind the life time of that type to the life time of the environment that is supposed to outlive the type system. You do that by passing the type to the function environment::keep_type_alive(). </p>
96</div><!-- contents --> 89</div><!-- contents -->
97<!-- start footer part --> 90<!-- start footer part -->
98<hr class="footer"/><address class="footer"><small> 91<hr class="footer"/><address class="footer"><small>
99Generated by &#160;<a href="http://www.doxygen.org/index.html"> 92Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.5
100<img class="footer" src="doxygen.png" alt="doxygen"/>
101</a> 1.8.5
102</small></address> 93</small></address>
103</body> 94</body>
104</html> 95</html>
generated by cgit (git 2.34.1) at 2025-11-01 03:13:33 +0000