1<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- 4(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com . 5Use, modification and distribution is subject to the Boost Software 6License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at 7http://www.boost.org/LICENSE_1_0.txt) 8--> 9<head> 10<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 11<link rel="stylesheet" type="text/css" href="../../../boost.css"> 12<link rel="stylesheet" type="text/css" href="style.css"> 13<title>Serialization - Reference</title> 14</head> 15<body link="#0000ff" vlink="#800080"> 16<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header"> 17 <tr> 18 <td valign="top" width="300"> 19 <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3> 20 </td> 21 <td valign="top"> 22 <h1 align="center">Serialization</h1> 23 <h2 align="center">Exception Safety</h2> 24 </td> 25 </tr> 26</table> 27<hr> 28The process of loading an archive may result in the creation of new objects. That 29same process may throw an exception at some point. In order to prevent memory leaks 30and invalid pointers, these situations must be considered. Unfortunately, there is 31no simple universal solution to this problem. The manner of addressing this must 32depend on the design of the data structures to be serialized. Below, we discuss 33varying scenarios in increasing order of difficulty. This discussion presumes that 34the class member functions are exception safe before considering serialization. 35That is, the destructor could be called at anytime without referencing 36an invalid pointer, or creating a memory leak. 37<ol> 38 <li><h4>class contains no pointers</h4> 39 No problem here. 40 <p> 41 <li><h4>class contains only <i>owned</i> pointers</h4> 42 From here on, we have to make a distinction between pointers used 43 to manage heap storage (<i>owned</i> pointers) and pointers used to refer 44 to related objects (<i>referenced</i> pointers). Programs containing <i>owned</i> 45 pointers must contain code for deleting these objects and returning the 46 deallocated storage to the heap. Programs containing <i>referenced</i> pointers 47 must be designed to ensure that no such <i>referenced</i> pointers are de-referenced 48 after the object pointed to has been destroyed and its storage returned 49 to the heap. If a pointer is stored in only one place, it must be an <i>owned</i> 50 pointer. 51 <p> 52 The load function traps any exceptions that occur between the time an object 53 is created and its pointer is stored. Should an exception occur while 54 reading an archive, the created object is deleted and the de-serialized 55 pointer is set to NULL. This ensures that there are no memory leaks. 56 The fact that there are no other copies of this pointer ensures that 57 no pointers are left invalid. The object's destructor should 58 be able to delete any other existing objects in the normal manner 59 without problem. 60 <a href="../test/test_delete_pointer.cpp" target="test_delete_pointer.cpp">test_delete_pointer.cpp</a> 61 illustrates this case. 62 <p> 63 <li><h4>class contains one or more <i>referenced</i> pointers</h4> 64 This situation can be further subdivided into two cases 65 <p> 66 <ol> 67 <li><h4><i>owned</i> pointers are always serialized before <i>referenced</i> pointers</h4> 68 Object tracking will ensure that no new objects will be created 69 by the loading of a <i>referenced</i> pointer. 70 If an exception occurs, <i>referenced</i> pointers will not need to be deleted 71 so there will be no memory leaks. The destructor of this class won't attempt to 72 delete these pointers so there will be no problem with dangling references. 73 <i>Owned</i> pointers are handled exactly as described above. 74 <p> 75 <li><h4>class contains <i>referenced</i> pointers which might be created by load</h4> 76 If a <i>referenced</i> pointer is loaded before its corresponding <i>owned</i> 77 pointer, the object will be allocated on the heap. In certain cases 78 it cannot be known which pointers were created by their owners and which 79 were created by the load function. To address this: 80 <ul> 81 <li>Trap exceptions with a <code style="white-space: normal">try/catch</code> block. 82 <li>Within the catch part, invoke the archive function 83 <code style="white-space: normal">delete_created_pointers()</code> to delete any pointers 84 created by the class load. Without other action, objects created in 85 this way would end up as memory leaks as they are not considered <i>owned</i> 86 pointers and hence aren't destroyed. 87 <li>The object's destructor won't try 88 to delete <i>referenced</i> pointers so any dangling references will 89 cause no harm. 90 </ul> 91 <a href="../example/demo_exception.cpp" target="demo_exception.cpp">demo_exception.cpp</a> 92 is a program that illustrates this case. 93 <p> 94 </ol> 95 <p> 96 <li><h4>Other cases</h4> 97 Situations not covered above are pointers for which the classifications of 98 <i>referenced</i> and <i>owned</i> are not applicable. This might occur where 99 pointers are created by one class but consumed and deleted by another. These 100 may be addressed with an ad hoc analysis similar to the above. As the 101 situation becomes more complex this becomes more difficult and error prone. 102 Eventually, it will be have to addressed by building heap management into the 103 pointer itself - that is into <code style="white-space: normal">boost::shared_ptr</code>. 104 The library includes serialization of <code style="white-space: normal">boost::shared_ptr</code>. As 105 previously mentioned, this required a tiny alteration in one of the 106 <code style="white-space: normal">boost::shared_ptr</code> implementation files in order to permit 107 access by the serialization system. 108</ol> 109<hr> 110<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004. 111Distributed under the Boost Software License, Version 1.0. (See 112accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 113</i></p> 114</body> 115</html> 116
