1<!DOCTYPE html> 2<html lang="en"> 3<head> 4<meta charset="UTF-8"> 5<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> 6<meta name="viewport" content="width=device-width, initial-scale=1.0"> 7<meta name="generator" content="Asciidoctor 1.5.8"> 8<meta name="author" content="Greg Colvin, Beman Dawes, Peter Dimov, Glen Fernandes"> 9<title>Boost.SmartPtr: The Smart Pointer Library</title> 10<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> 11<style> 12/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */ 13/* Uncomment @import statement below to use as custom stylesheet */ 14/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/ 15article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block} 16audio,canvas,video{display:inline-block} 17audio:not([controls]){display:none;height:0} 18script{display:none!important} 19html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} 20a{background:transparent} 21a:focus{outline:thin dotted} 22a:active,a:hover{outline:0} 23h1{font-size:2em;margin:.67em 0} 24abbr[title]{border-bottom:1px dotted} 25b,strong{font-weight:bold} 26dfn{font-style:italic} 27hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} 28mark{background:#ff0;color:#000} 29code,kbd,pre,samp{font-family:monospace;font-size:1em} 30pre{white-space:pre-wrap} 31q{quotes:"\201C" "\201D" "\2018" "\2019"} 32small{font-size:80%} 33sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} 34sup{top:-.5em} 35sub{bottom:-.25em} 36img{border:0} 37svg:not(:root){overflow:hidden} 38figure{margin:0} 39fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} 40legend{border:0;padding:0} 41button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} 42button,input{line-height:normal} 43button,select{text-transform:none} 44button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} 45button[disabled],html input[disabled]{cursor:default} 46input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} 47button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} 48textarea{overflow:auto;vertical-align:top} 49table{border-collapse:collapse;border-spacing:0} 50*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} 51html,body{font-size:100%} 52body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} 53a:hover{cursor:pointer} 54img,object,embed{max-width:100%;height:auto} 55object,embed{height:100%} 56img{-ms-interpolation-mode:bicubic} 57.left{float:left!important} 58.right{float:right!important} 59.text-left{text-align:left!important} 60.text-right{text-align:right!important} 61.text-center{text-align:center!important} 62.text-justify{text-align:justify!important} 63.hide{display:none} 64img,object,svg{display:inline-block;vertical-align:middle} 65textarea{height:auto;min-height:50px} 66select{width:100%} 67.center{margin-left:auto;margin-right:auto} 68.stretch{width:100%} 69.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} 70div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr} 71a{color:#2156a5;text-decoration:underline;line-height:inherit} 72a:hover,a:focus{color:#1d4b8f} 73a img{border:none} 74p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} 75p aside{font-size:.875em;line-height:1.35;font-style:italic} 76h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} 77h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} 78h1{font-size:2.125em} 79h2{font-size:1.6875em} 80h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} 81h4,h5{font-size:1.125em} 82h6{font-size:1em} 83hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} 84em,i{font-style:italic;line-height:inherit} 85strong,b{font-weight:bold;line-height:inherit} 86small{font-size:60%;line-height:inherit} 87code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} 88ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} 89ul,ol{margin-left:1.5em} 90ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} 91ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} 92ul.square{list-style-type:square} 93ul.circle{list-style-type:circle} 94ul.disc{list-style-type:disc} 95ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} 96dl dt{margin-bottom:.3125em;font-weight:bold} 97dl dd{margin-bottom:1.25em} 98abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} 99abbr{text-transform:none} 100blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} 101blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} 102blockquote cite::before{content:"\2014 \0020"} 103blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} 104blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} 105@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} 106h1{font-size:2.75em} 107h2{font-size:2.3125em} 108h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} 109h4{font-size:1.4375em}} 110table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede} 111table thead,table tfoot{background:#f7f8f7} 112table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} 113table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} 114table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7} 115table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6} 116h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} 117h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} 118.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} 119.clearfix::after,.float-group::after{clear:both} 120*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word} 121*:not(pre)>code.nobreak{word-wrap:normal} 122*:not(pre)>code.nowrap{white-space:nowrap} 123pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed} 124em em{font-style:normal} 125strong strong{font-weight:400} 126.keyseq{color:rgba(51,51,51,.8)} 127kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} 128.keyseq kbd:first-child{margin-left:0} 129.keyseq kbd:last-child{margin-right:0} 130.menuseq,.menuref{color:#000} 131.menuseq b:not(.caret),.menuref{font-weight:inherit} 132.menuseq{word-spacing:-.02em} 133.menuseq b.caret{font-size:1.25em;line-height:.8} 134.menuseq i.caret{font-weight:bold;text-align:center;width:.45em} 135b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} 136b.button::before{content:"[";padding:0 3px 0 2px} 137b.button::after{content:"]";padding:0 2px 0 3px} 138p a>code:hover{color:rgba(0,0,0,.9)} 139#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} 140#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} 141#header::after,#content::after,#footnotes::after,#footer::after{clear:both} 142#content{margin-top:1.25em} 143#content::before{content:none} 144#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} 145#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} 146#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} 147#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap} 148#header .details span:first-child{margin-left:-.125em} 149#header .details span.email a{color:rgba(0,0,0,.85)} 150#header .details br{display:none} 151#header .details br+span::before{content:"\00a0\2013\00a0"} 152#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} 153#header .details br+span#revremark::before{content:"\00a0|\00a0"} 154#header #revnumber{text-transform:capitalize} 155#header #revnumber::after{content:"\00a0"} 156#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} 157#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} 158#toc>ul{margin-left:.125em} 159#toc ul.sectlevel0>li>a{font-style:italic} 160#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} 161#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} 162#toc li{line-height:1.3334;margin-top:.3334em} 163#toc a{text-decoration:none} 164#toc a:active{text-decoration:underline} 165#toctitle{color:#7a2518;font-size:1.2em} 166@media screen and (min-width:768px){#toctitle{font-size:1.375em} 167body.toc2{padding-left:15em;padding-right:0} 168#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} 169#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} 170#toc.toc2>ul{font-size:.9em;margin-bottom:0} 171#toc.toc2 ul ul{margin-left:0;padding-left:1em} 172#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} 173body.toc2.toc-right{padding-left:0;padding-right:15em} 174body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} 175@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} 176#toc.toc2{width:20em} 177#toc.toc2 #toctitle{font-size:1.375em} 178#toc.toc2>ul{font-size:.95em} 179#toc.toc2 ul ul{padding-left:1.25em} 180body.toc2.toc-right{padding-left:0;padding-right:20em}} 181#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} 182#content #toc>:first-child{margin-top:0} 183#content #toc>:last-child{margin-bottom:0} 184#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em} 185#footer-text{color:rgba(255,255,255,.8);line-height:1.44} 186#content{margin-bottom:.625em} 187.sect1{padding-bottom:.625em} 188@media screen and (min-width:768px){#content{margin-bottom:1.25em} 189.sect1{padding-bottom:1.25em}} 190.sect1:last-child{padding-bottom:0} 191.sect1+.sect1{border-top:1px solid #e7e7e9} 192#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} 193#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} 194#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} 195#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} 196#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} 197.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} 198.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} 199table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} 200.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} 201table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit} 202.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} 203.admonitionblock>table td.icon{text-align:center;width:80px} 204.admonitionblock>table td.icon img{max-width:none} 205.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} 206.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)} 207.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} 208.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px} 209.exampleblock>.content>:first-child{margin-top:0} 210.exampleblock>.content>:last-child{margin-bottom:0} 211.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} 212.sidebarblock>:first-child{margin-top:0} 213.sidebarblock>:last-child{margin-bottom:0} 214.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} 215.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} 216.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8} 217.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1} 218.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em} 219@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}} 220@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}} 221.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal} 222.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)} 223.listingblock pre.highlightjs{padding:0} 224.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} 225.listingblock pre.prettyprint{border-width:0} 226.listingblock>.content{position:relative} 227.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999} 228.listingblock:hover code[data-lang]::before{display:block} 229.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999} 230.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} 231table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none} 232table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45} 233table.pyhltable td.code{padding-left:.75em;padding-right:0} 234pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf} 235pre.pygments .lineno{display:inline-block;margin-right:.25em} 236table.pyhltable .linenodiv{background:none!important;padding-right:0!important} 237.quoteblock{margin:0 1em 1.25em 1.5em;display:table} 238.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em} 239.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} 240.quoteblock blockquote{margin:0;padding:0;border:0} 241.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} 242.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} 243.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} 244.verseblock{margin:0 1em 1.25em} 245.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} 246.verseblock pre strong{font-weight:400} 247.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} 248.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} 249.quoteblock .attribution br,.verseblock .attribution br{display:none} 250.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} 251.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} 252.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0} 253.quoteblock.abstract{margin:0 1em 1.25em;display:block} 254.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} 255.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf} 256.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} 257.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0} 258table.tableblock{max-width:100%;border-collapse:separate} 259p.tableblock:last-child{margin-bottom:0} 260td.tableblock>.content{margin-bottom:-1.25em} 261table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} 262table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0} 263table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0} 264table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0} 265table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px} 266table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0} 267table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0} 268table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0} 269table.frame-all{border-width:1px} 270table.frame-sides{border-width:0 1px} 271table.frame-topbot,table.frame-ends{border-width:1px 0} 272table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7} 273table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none} 274th.halign-left,td.halign-left{text-align:left} 275th.halign-right,td.halign-right{text-align:right} 276th.halign-center,td.halign-center{text-align:center} 277th.valign-top,td.valign-top{vertical-align:top} 278th.valign-bottom,td.valign-bottom{vertical-align:bottom} 279th.valign-middle,td.valign-middle{vertical-align:middle} 280table thead th,table tfoot th{font-weight:bold} 281tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7} 282tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} 283p.tableblock>code:only-child{background:none;padding:0} 284p.tableblock{font-size:1em} 285td>div.verse{white-space:pre} 286ol{margin-left:1.75em} 287ul li ol{margin-left:1.5em} 288dl dd{margin-left:1.125em} 289dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} 290ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} 291ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} 292ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} 293ul.unstyled,ol.unstyled{margin-left:0} 294ul.checklist{margin-left:.625em} 295ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} 296ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em} 297ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} 298ul.inline>li{margin-left:1.25em} 299.unstyled dl dt{font-weight:400;font-style:normal} 300ol.arabic{list-style-type:decimal} 301ol.decimal{list-style-type:decimal-leading-zero} 302ol.loweralpha{list-style-type:lower-alpha} 303ol.upperalpha{list-style-type:upper-alpha} 304ol.lowerroman{list-style-type:lower-roman} 305ol.upperroman{list-style-type:upper-roman} 306ol.lowergreek{list-style-type:lower-greek} 307.hdlist>table,.colist>table{border:0;background:none} 308.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} 309td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} 310td.hdlist1{font-weight:bold;padding-bottom:1.25em} 311.literalblock+.colist,.listingblock+.colist{margin-top:-.5em} 312.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} 313.colist td:not([class]):first-child img{max-width:none} 314.colist td:not([class]):last-child{padding:.25em 0} 315.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd} 316.imageblock.left{margin:.25em .625em 1.25em 0} 317.imageblock.right{margin:.25em 0 1.25em .625em} 318.imageblock>.title{margin-bottom:0} 319.imageblock.thumb,.imageblock.th{border-width:6px} 320.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} 321.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} 322.image.left{margin-right:.625em} 323.image.right{margin-left:.625em} 324a.image{text-decoration:none;display:inline-block} 325a.image object{pointer-events:none} 326sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} 327sup.footnote a,sup.footnoteref a{text-decoration:none} 328sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} 329#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} 330#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} 331#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} 332#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} 333#footnotes .footnote:last-of-type{margin-bottom:0} 334#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} 335.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} 336.gist .file-data>table td.line-data{width:99%} 337div.unbreakable{page-break-inside:avoid} 338.big{font-size:larger} 339.small{font-size:smaller} 340.underline{text-decoration:underline} 341.overline{text-decoration:overline} 342.line-through{text-decoration:line-through} 343.aqua{color:#00bfbf} 344.aqua-background{background-color:#00fafa} 345.black{color:#000} 346.black-background{background-color:#000} 347.blue{color:#0000bf} 348.blue-background{background-color:#0000fa} 349.fuchsia{color:#bf00bf} 350.fuchsia-background{background-color:#fa00fa} 351.gray{color:#606060} 352.gray-background{background-color:#7d7d7d} 353.green{color:#006000} 354.green-background{background-color:#007d00} 355.lime{color:#00bf00} 356.lime-background{background-color:#00fa00} 357.maroon{color:#600000} 358.maroon-background{background-color:#7d0000} 359.navy{color:#000060} 360.navy-background{background-color:#00007d} 361.olive{color:#606000} 362.olive-background{background-color:#7d7d00} 363.purple{color:#600060} 364.purple-background{background-color:#7d007d} 365.red{color:#bf0000} 366.red-background{background-color:#fa0000} 367.silver{color:#909090} 368.silver-background{background-color:#bcbcbc} 369.teal{color:#006060} 370.teal-background{background-color:#007d7d} 371.white{color:#bfbfbf} 372.white-background{background-color:#fafafa} 373.yellow{color:#bfbf00} 374.yellow-background{background-color:#fafa00} 375span.icon>.fa{cursor:default} 376a span.icon>.fa{cursor:inherit} 377.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} 378.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} 379.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} 380.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} 381.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} 382.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} 383.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} 384.conum[data-value] *{color:#fff!important} 385.conum[data-value]+b{display:none} 386.conum[data-value]::after{content:attr(data-value)} 387pre .conum[data-value]{position:relative;top:-.125em} 388b.conum *{color:inherit!important} 389.conum:not([data-value]):empty{display:none} 390dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} 391h1,h2,p,td.content,span.alt{letter-spacing:-.01em} 392p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} 393p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} 394p{margin-bottom:1.25rem} 395.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} 396.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} 397.print-only{display:none!important} 398@page{margin:1.25cm .75cm} 399@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} 400html{font-size:80%} 401a{color:inherit!important;text-decoration:underline!important} 402a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} 403a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} 404abbr[title]::after{content:" (" attr(title) ")"} 405pre,blockquote,tr,img,object,svg{page-break-inside:avoid} 406thead{display:table-header-group} 407svg{max-width:100%} 408p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} 409h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} 410#toc,.sidebarblock,.exampleblock>.content{background:none!important} 411#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} 412body.book #header{text-align:center} 413body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} 414body.book #header .details{border:0!important;display:block;padding:0!important} 415body.book #header .details span:first-child{margin-left:0!important} 416body.book #header .details br{display:block} 417body.book #header .details br+span::before{content:none!important} 418body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} 419body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} 420.listingblock code[data-lang]::before{display:block} 421#footer{padding:0 .9375em} 422.hide-on-print{display:none!important} 423.print-only{display:block!important} 424.hide-for-print{display:none!important} 425.show-for-print{display:inherit!important}} 426@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem} 427.sect1{padding:0!important} 428.sect1+.sect1{border:0} 429#footer{background:none} 430#footer-text{color:rgba(0,0,0,.6);font-size:.9em}} 431@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} 432</style> 433</head> 434<body class="article toc2 toc-left"> 435<div id="header"> 436<h1>Boost.SmartPtr: The Smart Pointer Library</h1> 437<div class="details"> 438<span id="author" class="author">Greg Colvin, Beman Dawes, Peter Dimov, Glen Fernandes</span><br> 439</div> 440<div id="toc" class="toc2"> 441<div id="toctitle">Table of Contents</div> 442<ul class="sectlevel1"> 443<li><a href="#introduction">Introduction</a></li> 444<li><a href="#changelog">Revision History</a> 445<ul class="sectlevel2"> 446<li><a href="#changelog_changes_in_1_74_0">Changes in 1.74.0</a></li> 447<li><a href="#changelog_changes_in_1_72_0">Changes in 1.72.0</a></li> 448<li><a href="#changelog_changes_in_1_71_0">Changes in 1.71.0</a></li> 449<li><a href="#changelog_changes_in_1_65_0">Changes in 1.65.0</a></li> 450</ul> 451</li> 452<li><a href="#scoped_ptr">scoped_ptr: Scoped Object Ownership</a> 453<ul class="sectlevel2"> 454<li><a href="#scoped_ptr_description">Description</a></li> 455<li><a href="#scoped_ptr_synopsis">Synopsis</a></li> 456<li><a href="#scoped_ptr_members">Members</a></li> 457<li><a href="#scoped_ptr_free_functions">Free Functions</a></li> 458<li><a href="#scoped_ptr_example">Example</a></li> 459<li><a href="#scoped_ptr_rationale">Rationale</a></li> 460<li><a href="#scoped_ptr_handlebody_idiom">Handle/Body Idiom</a></li> 461<li><a href="#scoped_ptr_frequently_asked_questions">Frequently Asked Questions</a></li> 462</ul> 463</li> 464<li><a href="#scoped_array">scoped_array: Scoped Array Ownership</a> 465<ul class="sectlevel2"> 466<li><a href="#scoped_array_description">Description</a></li> 467<li><a href="#scoped_array_synopsis">Synopsis</a></li> 468<li><a href="#scoped_array_members">Members</a></li> 469<li><a href="#scoped_array_free_functions">Free Functions</a></li> 470</ul> 471</li> 472<li><a href="#shared_ptr">shared_ptr: Shared Ownership</a> 473<ul class="sectlevel2"> 474<li><a href="#shared_ptr_description">Description</a></li> 475<li><a href="#shared_ptr_best_practices">Best Practices</a></li> 476<li><a href="#shared_ptr_synopsis">Synopsis</a></li> 477<li><a href="#shared_ptr_members">Members</a></li> 478<li><a href="#shared_ptr_free_functions">Free Functions</a></li> 479<li><a href="#shared_ptr_example">Example</a></li> 480<li><a href="#shared_ptr_handlebody_idiom">Handle/Body Idiom</a></li> 481<li><a href="#shared_ptr_thread_safety">Thread Safety</a></li> 482<li><a href="#shared_ptr_frequently_asked_questions">Frequently Asked Questions</a></li> 483</ul> 484</li> 485<li><a href="#weak_ptr">weak_ptr: Non-owning Observer</a> 486<ul class="sectlevel2"> 487<li><a href="#weak_ptr_description">Description</a></li> 488<li><a href="#weak_ptr_synopsis">Synopsis</a></li> 489<li><a href="#weak_ptr_members">Members</a></li> 490<li><a href="#weak_ptr_free_functions">Free Functions</a></li> 491<li><a href="#weak_ptr_frequently_asked_questions">Frequently Asked Questions</a></li> 492</ul> 493</li> 494<li><a href="#make_shared">make_shared: Creating shared_ptr</a> 495<ul class="sectlevel2"> 496<li><a href="#make_shared_description">Description</a></li> 497<li><a href="#make_shared_rationale">Rationale</a></li> 498<li><a href="#make_shared_synopsis">Synopsis</a></li> 499<li><a href="#make_shared_common_requirements">Common Requirements</a></li> 500<li><a href="#make_shared_free_functions">Free Functions</a></li> 501</ul> 502</li> 503<li><a href="#enable_shared_from_this">enable_shared_from_this</a> 504<ul class="sectlevel2"> 505<li><a href="#enable_shared_from_this_description">Description</a></li> 506<li><a href="#enable_shared_from_this_example">Example</a></li> 507<li><a href="#enable_shared_from_this_synopsis">Synopsis</a></li> 508<li><a href="#enable_shared_from_this_members">Members</a></li> 509</ul> 510</li> 511<li><a href="#enable_shared_from">enable_shared_from</a> 512<ul class="sectlevel2"> 513<li><a href="#enable_shared_from_description">Description</a></li> 514<li><a href="#enable_shared_from_example">Example</a></li> 515<li><a href="#enable_shared_from_synopsis">Synopsis</a></li> 516<li><a href="#enable_shared_from_functions">Functions</a></li> 517</ul> 518</li> 519<li><a href="#make_unique">make_unique: Creating unique_ptr</a> 520<ul class="sectlevel2"> 521<li><a href="#make_unique_description">Description</a></li> 522<li><a href="#make_unique_rationale">Rationale</a></li> 523<li><a href="#make_unique_synopsis">Synopsis</a></li> 524<li><a href="#make_unique_free_functions">Free Functions</a></li> 525</ul> 526</li> 527<li><a href="#allocate_unique">allocate_unique: Creating unique_ptr</a> 528<ul class="sectlevel2"> 529<li><a href="#allocate_unique_description">Description</a></li> 530<li><a href="#allocate_unique_rationale">Rationale</a></li> 531<li><a href="#allocate_unique_synopsis">Synopsis</a></li> 532<li><a href="#allocate_unique_common_requirements">Common Requirements</a></li> 533<li><a href="#allocate_unique_free_functions">Free Functions</a></li> 534<li><a href="#allocate_unique_deleter">Deleter</a></li> 535</ul> 536</li> 537<li><a href="#intrusive_ptr">intrusive_ptr: Managing Objects with Embedded Counts</a> 538<ul class="sectlevel2"> 539<li><a href="#intrusive_ptr_description">Description</a></li> 540<li><a href="#intrusive_ptr_synopsis">Synopsis</a></li> 541<li><a href="#intrusive_ptr_members">Members</a></li> 542<li><a href="#intrusive_ptr_free_functions">Free Functions</a></li> 543</ul> 544</li> 545<li><a href="#intrusive_ref_counter">intrusive_ref_counter</a> 546<ul class="sectlevel2"> 547<li><a href="#intrusive_ref_counter_description">Description</a></li> 548<li><a href="#intrusive_ref_counter_synopsis">Synopsis</a></li> 549<li><a href="#intrusive_ref_counter_members">Members</a></li> 550<li><a href="#intrusive_ref_counter_free_functions">Free Functions</a></li> 551</ul> 552</li> 553<li><a href="#local_shared_ptr">local_shared_ptr: Shared Ownership within a Single Thread</a> 554<ul class="sectlevel2"> 555<li><a href="#local_shared_ptr_description">Description</a></li> 556<li><a href="#local_shared_ptr_synopsis">Synopsis</a></li> 557<li><a href="#local_shared_ptr_members">Members</a></li> 558<li><a href="#local_shared_ptr_free_functions">Free Functions</a></li> 559</ul> 560</li> 561<li><a href="#make_local_shared">make_local_shared: Creating local_shared_ptr</a> 562<ul class="sectlevel2"> 563<li><a href="#make_local_shared_description">Description</a></li> 564<li><a href="#make_local_shared_synopsis">Synopsis</a></li> 565<li><a href="#make_local_shared_description_2">Description</a></li> 566</ul> 567</li> 568<li><a href="#pointer_cast">Generic Pointer Casts</a> 569<ul class="sectlevel2"> 570<li><a href="#pointer_cast_description">Description</a></li> 571<li><a href="#pointer_cast_rationale">Rationale</a></li> 572<li><a href="#pointer_cast_synopsis">Synopsis</a></li> 573<li><a href="#pointer_cast_free_functions">Free Functions</a></li> 574<li><a href="#pointer_cast_example">Example</a></li> 575</ul> 576</li> 577<li><a href="#pointer_to_other">pointer_to_other</a> 578<ul class="sectlevel2"> 579<li><a href="#pointer_to_other_description">Description</a></li> 580<li><a href="#pointer_to_other_rationale">Rationale</a></li> 581<li><a href="#pointer_to_other_synopsis">Synopsis</a></li> 582<li><a href="#pointer_to_other_example">Example</a></li> 583</ul> 584</li> 585<li><a href="#atomic_shared_ptr">atomic_shared_ptr</a> 586<ul class="sectlevel2"> 587<li><a href="#atomic_shared_ptr_description">Description</a></li> 588<li><a href="#atomic_shared_ptr_synopsis">Synopsis</a></li> 589<li><a href="#atomic_shared_ptr_members">Members</a></li> 590</ul> 591</li> 592<li><a href="#owner_less">owner_less</a> 593<ul class="sectlevel2"> 594<li><a href="#owner_less_description">Description</a></li> 595<li><a href="#owner_less_synopsis">Synopsis</a></li> 596<li><a href="#owner_less_members">Members</a></li> 597</ul> 598</li> 599<li><a href="#owner_equal_to">owner_equal_to</a> 600<ul class="sectlevel2"> 601<li><a href="#owner_equal_to_description">Description</a></li> 602<li><a href="#owner_equal_to_synopsis">Synopsis</a></li> 603<li><a href="#owner_equal_to_members">Members</a></li> 604</ul> 605</li> 606<li><a href="#owner_hash">owner_hash</a> 607<ul class="sectlevel2"> 608<li><a href="#owner_hash_to_description">Description</a></li> 609<li><a href="#owner_hash_to_example">Example</a></li> 610<li><a href="#owner_hash_to_synopsis">Synopsis</a></li> 611<li><a href="#owner_hash_to_members">Members</a></li> 612</ul> 613</li> 614<li><a href="#techniques">Appendix A: Smart Pointer Programming Techniques</a> 615<ul class="sectlevel2"> 616<li><a href="#techniques_incomplete">Using incomplete classes for implementation hiding</a></li> 617<li><a href="#techniques_the_pimpl_idiom">The "Pimpl" idiom</a></li> 618<li><a href="#techniques_using_abstract_classes_for_implementation_hiding">Using abstract classes for implementation hiding</a></li> 619<li><a href="#techniques_preventing_delete_px_get">Preventing <code>delete px.get()</code></a></li> 620<li><a href="#techniques_encapsulating_allocation_details_wrapping_factory_functions">Encapsulating allocation details, wrapping factory functions</a></li> 621<li><a href="#techniques_static">Using a shared_ptr to hold a pointer to a statically allocated object</a></li> 622<li><a href="#techniques_using_a_shared_ptr_to_hold_a_pointer_to_a_com_object">Using a shared_ptr to hold a pointer to a COM Object</a></li> 623<li><a href="#techniques_intrusive">Using a shared_ptr to hold a pointer to an object with an embedded reference count</a></li> 624<li><a href="#techniques_using_a_shared_ptr_to_hold_another_shared_ownership_smart_pointer">Using a shared_ptr to hold another shared ownership smart pointer</a></li> 625<li><a href="#techniques_from_raw">Obtaining a shared_ptr from a raw pointer</a></li> 626<li><a href="#techniques_obtaining_a_shared_ptr_weak_ptr_to_this_in_a_constructor">Obtaining a shared_ptr (weak_ptr) to this in a constructor</a></li> 627<li><a href="#techniques_obtaining_a_shared_ptr_to_this">Obtaining a shared_ptr to this</a></li> 628<li><a href="#techniques_using_shared_ptr_as_a_smart_counted_handle">Using shared_ptr as a smart counted handle</a></li> 629<li><a href="#techniques_using_shared_ptr_to_execute_code_on_block_exit">Using shared_ptr to execute code on block exit</a></li> 630<li><a href="#techniques_using_shared_ptrvoid_to_hold_an_arbitrary_object">Using shared_ptr<void> to hold an arbitrary object</a></li> 631<li><a href="#techniques_associating_arbitrary_data_with_heterogeneous_shared_ptr_instances">Associating arbitrary data with heterogeneous <code>shared_ptr</code> instances</a></li> 632<li><a href="#techniques_using_shared_ptr_as_a_copyconstructible_mutex_lock">Using <code>shared_ptr</code> as a <code>CopyConstructible</code> mutex lock</a></li> 633<li><a href="#techniques_using_shared_ptr_to_wrap_member_function_calls">Using shared_ptr to wrap member function calls</a></li> 634<li><a href="#techniques_delayed_deallocation">Delayed deallocation</a></li> 635<li><a href="#techniques_weak_without_shared">Weak pointers to objects not managed by a shared_ptr</a></li> 636</ul> 637</li> 638<li><a href="#history">Appendix B: History and Acknowledgments</a> 639<ul class="sectlevel2"> 640<li><a href="#history_summer_1994">Summer 1994</a></li> 641<li><a href="#history_october_1998">October 1998</a></li> 642<li><a href="#history_may_1999">May 1999</a></li> 643<li><a href="#history_september_1999">September 1999</a></li> 644<li><a href="#history_november_1999">November 1999</a></li> 645<li><a href="#history_may_2001">May 2001</a></li> 646<li><a href="#history_january_2002">January 2002</a></li> 647<li><a href="#history_march_2003">March 2003</a></li> 648<li><a href="#history_july_2007">July 2007</a></li> 649<li><a href="#history_november_2012">November 2012</a></li> 650<li><a href="#history_april_2013">April 2013</a></li> 651<li><a href="#history_february_2014">February 2014</a></li> 652<li><a href="#history_february_2017">February 2017</a></li> 653<li><a href="#history_june_2017">June 2017</a></li> 654<li><a href="#history_august_2019">August 2019</a></li> 655</ul> 656</li> 657<li><a href="#shared_array">Appendix C: shared_array (deprecated)</a> 658<ul class="sectlevel2"> 659<li><a href="#shared_array_description">Description</a></li> 660<li><a href="#shared_array_synopsis">Synopsis</a></li> 661<li><a href="#shared_array_members">Members</a></li> 662<li><a href="#shared_array_free_functions">Free Functions</a></li> 663</ul> 664</li> 665<li><a href="#copyright">Appendix D: Copyright and License</a></li> 666</ul> 667</div> 668</div> 669<div id="content"> 670<div class="sect1"> 671<h2 id="introduction">Introduction</h2> 672<div class="sectionbody"> 673<div class="paragraph"> 674<p>Smart pointers are objects which store pointers to dynamically allocated (heap) objects. 675They behave much like built-in C++ pointers except that they automatically delete the object 676pointed to at the appropriate time. Smart pointers are particularly useful in the face of 677exceptions as they ensure proper destruction of dynamically allocated objects. They can also be 678used to keep track of dynamically allocated objects shared by multiple owners.</p> 679</div> 680<div class="paragraph"> 681<p>Conceptually, smart pointers are seen as owning the object pointed to, and thus responsible for 682deletion of the object when it is no longer needed. As such, they are examples of the "resource 683acquisition is initialization" idiom described in Bjarne Stroustrup’s "The C++ Programming Language", 6843rd edition, Section 14.4, Resource Management.</p> 685</div> 686<div class="paragraph"> 687<p>This library provides six smart pointer class templates:</p> 688</div> 689<div class="ulist"> 690<ul> 691<li> 692<p><code><a href="#scoped_ptr">scoped_ptr</a></code>, used to contain ownership of a dynamically allocated object to the current scope;</p> 693</li> 694<li> 695<p><code><a href="#scoped_array">scoped_array</a></code>, which provides scoped ownership for a dynamically allocated array;</p> 696</li> 697<li> 698<p><code><a href="#shared_ptr">shared_ptr</a></code>, a versatile tool for managing shared ownership of an object or array;</p> 699</li> 700<li> 701<p><code><a href="#weak_ptr">weak_ptr</a></code>, a non-owning observer to a <code>shared_ptr</code>-managed object that can be promoted temporarily to <code>shared_ptr</code>;</p> 702</li> 703<li> 704<p><code><a href="#intrusive_ptr">intrusive_ptr</a></code>, a pointer to objects with an embedded reference count;</p> 705</li> 706<li> 707<p><code><a href="#local_shared_ptr">local_shared_ptr</a></code>, providing shared ownership within a single thread.</p> 708</li> 709</ul> 710</div> 711<div class="paragraph"> 712<p><code>shared_ptr</code> and <code>weak_ptr</code> are part of the C++ standard since its 2011 iteration.</p> 713</div> 714<div class="paragraph"> 715<p>In addition, the library contains the following supporting utility functions and classes:</p> 716</div> 717<div class="ulist"> 718<ul> 719<li> 720<p><code><a href="#make_shared">make_shared</a></code> and <code>allocate_shared</code>, factory functions for creating objects that return a <code>shared_ptr</code>;</p> 721</li> 722<li> 723<p><code><a href="#make_unique">make_unique</a></code>, a factory function returning <code>std::unique_ptr</code>;</p> 724</li> 725<li> 726<p><code><a href="#allocate_unique">allocate_unique</a></code>, a factory function for creating objects using an allocator that returns a <code>std::unique_ptr</code>;</p> 727</li> 728<li> 729<p><code><a href="#enable_shared_from_this">enable_shared_from_this</a></code>, a helper base class that enables the acquisition of a <code>shared_ptr</code> pointing to <code>this</code>;</p> 730</li> 731<li> 732<p><code><a href="#enable_shared_from">enable_shared_from</a></code>, a newer and better replacement for <code>enable_shared_from_this</code>;</p> 733</li> 734<li> 735<p><code><a href="#pointer_to_other">pointer_to_other</a></code>, a helper trait for converting one smart pointer type to another;</p> 736</li> 737<li> 738<p><code><a href="#pointer_cast">static_pointer_cast</a></code> and companions, generic smart pointer casts;</p> 739</li> 740<li> 741<p><code><a href="#intrusive_ref_counter">intrusive_ref_counter</a></code>, a helper base class containing a reference count.</p> 742</li> 743<li> 744<p><code><a href="#atomic_shared_ptr">atomic_shared_ptr</a></code>, a helper class implementing the interface of <code>std::atomic</code> for a value of type <code>shared_ptr</code>.</p> 745</li> 746</ul> 747</div> 748<div class="paragraph"> 749<p>As a general rule, the destructor or <code>operator delete</code> for an object managed by pointers in the library 750are not allowed to throw exceptions.</p> 751</div> 752</div> 753</div> 754<div class="sect1"> 755<h2 id="changelog">Revision History</h2> 756<div class="sectionbody"> 757<div class="sect2"> 758<h3 id="changelog_changes_in_1_74_0">Changes in 1.74.0</h3> 759<div class="ulist"> 760<ul> 761<li> 762<p>Added <code>owner_equals</code> to <code>shared_ptr</code>, <code>weak_ptr</code>, <code>local_shared_ptr</code></p> 763</li> 764<li> 765<p>Added <code>owner_hash_value</code> to <code>shared_ptr</code>, <code>weak_ptr</code></p> 766</li> 767<li> 768<p>Added <code>owner_equal_to</code>, <code>owner_hash</code></p> 769</li> 770<li> 771<p>Added <code>std::hash</code> specializations for <code>shared_ptr</code>, <code>local_shared_ptr</code></p> 772</li> 773<li> 774<p>Added <code>boost::hash</code> support to, and <code>std::hash</code>, <code>std::equal_to</code> 775specializations for, <code>weak_ptr</code></p> 776</li> 777</ul> 778</div> 779</div> 780<div class="sect2"> 781<h3 id="changelog_changes_in_1_72_0">Changes in 1.72.0</h3> 782<div class="ulist"> 783<ul> 784<li> 785<p>Added <code>allocate_unique</code></p> 786</li> 787</ul> 788</div> 789</div> 790<div class="sect2"> 791<h3 id="changelog_changes_in_1_71_0">Changes in 1.71.0</h3> 792<div class="ulist"> 793<ul> 794<li> 795<p>Added aliasing constructors to <code>weak_ptr</code></p> 796</li> 797<li> 798<p>Added <code>weak_ptr<T>::empty()</code></p> 799</li> 800<li> 801<p>Added <code>enable_shared_from</code>, <code>shared_from</code>, and <code>weak_from</code></p> 802</li> 803</ul> 804</div> 805</div> 806<div class="sect2"> 807<h3 id="changelog_changes_in_1_65_0">Changes in 1.65.0</h3> 808<div class="ulist"> 809<ul> 810<li> 811<p>Added <code>atomic_shared_ptr</code></p> 812</li> 813<li> 814<p>Added <code>local_shared_ptr</code>, <code>make_local_shared</code></p> 815</li> 816</ul> 817</div> 818</div> 819</div> 820</div> 821<div class="sect1"> 822<h2 id="scoped_ptr">scoped_ptr: Scoped Object Ownership</h2> 823<div class="sectionbody"> 824<div class="sect2"> 825<h3 id="scoped_ptr_description">Description</h3> 826<div class="paragraph"> 827<p>The <code>scoped_ptr</code> class template stores a pointer to a dynamically allocated object. 828(Dynamically allocated objects are allocated with the C++ <code>new</code> expression.) The 829object pointed to is guaranteed to be deleted, either on destruction of the <code>scoped_ptr</code>, 830or via an explicit <code>reset</code>. See the <a href="#scoped_ptr_example">example</a>.</p> 831</div> 832<div class="paragraph"> 833<p><code>scoped_ptr</code> is a simple solution for simple needs. It supplies a basic "resource acquisition 834is initialization" facility, without shared-ownership or transfer-of-ownership semantics. 835Both its name and enforcement of semantics (by being noncopyable) signal its intent to retain 836ownership solely within the current scope. Because it is noncopyable, it is safer than <code>shared_ptr</code> 837for pointers which should not be copied.</p> 838</div> 839<div class="paragraph"> 840<p>Because <code>scoped_ptr</code> is simple, in its usual implementation every operation is as fast as for a 841built-in pointer and it has no more space overhead that a built-in pointer.</p> 842</div> 843<div class="paragraph"> 844<p><code>scoped_ptr</code> cannot be used in C++ Standard Library containers. Use <code>shared_ptr</code> or <code>std::unique_ptr</code> 845if you need a smart pointer that can.</p> 846</div> 847<div class="paragraph"> 848<p><code>scoped_ptr</code> cannot correctly hold a pointer to a dynamically allocated array. See <code>scoped_array</code> for that usage.</p> 849</div> 850<div class="paragraph"> 851<p>The class template is parameterized on <code>T</code>, the type of the object pointed to. Destroying <code>T</code> must not thow exceptions, 852and <code>T</code> must be complete at the point <code>scoped_ptr<T>::~scoped_ptr</code> is instantiated.</p> 853</div> 854</div> 855<div class="sect2"> 856<h3 id="scoped_ptr_synopsis">Synopsis</h3> 857<div class="paragraph"> 858<p><code>scoped_ptr</code> is defined in <code><boost/smart_ptr/scoped_ptr.hpp></code>.</p> 859</div> 860<div class="listingblock"> 861<div class="content"> 862<pre class="highlight"><code>namespace boost { 863 864 template<class T> class scoped_ptr { 865 private: 866 867 scoped_ptr(scoped_ptr const&); 868 scoped_ptr& operator=(scoped_ptr const&); 869 870 void operator==(scoped_ptr const&) const; 871 void operator!=(scoped_ptr const&) const; 872 873 public: 874 875 typedef T element_type; 876 877 explicit scoped_ptr(T * p = 0) noexcept; 878 ~scoped_ptr() noexcept; 879 880 void reset(T * p = 0) noexcept; 881 882 T & operator*() const noexcept; 883 T * operator->() const noexcept; 884 T * get() const noexcept; 885 886 explicit operator bool() const noexcept; 887 888 void swap(scoped_ptr & b) noexcept; 889 }; 890 891 template<class T> void swap(scoped_ptr<T> & a, scoped_ptr<T> & b) noexcept; 892 893 template<class T> 894 bool operator==( scoped_ptr<T> const & p, std::nullptr_t ) noexcept; 895 template<class T> 896 bool operator==( std::nullptr_t, scoped_ptr<T> const & p ) noexcept; 897 898 template<class T> 899 bool operator!=( scoped_ptr<T> const & p, std::nullptr_t ) noexcept; 900 template<class T> 901 bool operator!=( std::nullptr_t, scoped_ptr<T> const & p ) noexcept; 902}</code></pre> 903</div> 904</div> 905</div> 906<div class="sect2"> 907<h3 id="scoped_ptr_members">Members</h3> 908<div class="sect3"> 909<h4 id="scoped_ptr_element_type">element_type</h4> 910<div class="literalblock"> 911<div class="content"> 912<pre>typedef T element_type;</pre> 913</div> 914</div> 915<div class="paragraph"> 916<p>Provides the type of the stored pointer.</p> 917</div> 918</div> 919<div class="sect3"> 920<h4 id="scoped_ptr_constructor">constructor</h4> 921<div class="literalblock"> 922<div class="content"> 923<pre>explicit scoped_ptr(T * p = 0) noexcept;</pre> 924</div> 925</div> 926<div class="paragraph"> 927<p>Constructs a <code>scoped_ptr</code>, storing a copy of <code>p</code>, which must have been allocated via a 928C++ <code>new</code> expression or be 0. <code>T</code> is not required be a complete type.</p> 929</div> 930</div> 931<div class="sect3"> 932<h4 id="scoped_ptr_destructor">destructor</h4> 933<div class="literalblock"> 934<div class="content"> 935<pre>~scoped_ptr() noexcept;</pre> 936</div> 937</div> 938<div class="paragraph"> 939<p>Destroys the object pointed to by the stored pointer, if any, as if by using 940<code>delete this->get()</code>. <code>T</code> must be a complete type.</p> 941</div> 942</div> 943<div class="sect3"> 944<h4 id="scoped_ptr_reset">reset</h4> 945<div class="literalblock"> 946<div class="content"> 947<pre>void reset(T * p = 0) noexcept;</pre> 948</div> 949</div> 950<div class="paragraph"> 951<p>Deletes the object pointed to by the stored pointer and then stores a copy of 952<code>p</code>, which must have been allocated via a C++ <code>new</code> expression or be 0.</p> 953</div> 954<div class="paragraph"> 955<p>Since the previous object needs to be deleted, <code>T</code> must be a complete type.</p> 956</div> 957</div> 958<div class="sect3"> 959<h4 id="scoped_ptr_indirection">indirection</h4> 960<div class="literalblock"> 961<div class="content"> 962<pre>T & operator*() const noexcept;</pre> 963</div> 964</div> 965<div class="paragraph"> 966<p>Returns a reference to the object pointed to by the stored pointer. Behavior is undefined if the stored pointer is 0.</p> 967</div> 968<div class="literalblock"> 969<div class="content"> 970<pre>T * operator->() const noexcept;</pre> 971</div> 972</div> 973<div class="paragraph"> 974<p>Returns the stored pointer. Behavior is undefined if the stored pointer is 0.</p> 975</div> 976</div> 977<div class="sect3"> 978<h4 id="scoped_ptr_get">get</h4> 979<div class="literalblock"> 980<div class="content"> 981<pre>T * get() const noexcept;</pre> 982</div> 983</div> 984<div class="paragraph"> 985<p>Returns the stored pointer. <code>T</code> need not be a complete type.</p> 986</div> 987</div> 988<div class="sect3"> 989<h4 id="scoped_ptr_conversions">conversions</h4> 990<div class="literalblock"> 991<div class="content"> 992<pre>explicit operator bool () const noexcept; // never throws</pre> 993</div> 994</div> 995<div class="paragraph"> 996<p>Returns <code>get() != 0</code>.</p> 997</div> 998<div class="admonitionblock note"> 999<table> 1000<tr> 1001<td class="icon"> 1002<div class="title">Note</div> 1003</td> 1004<td class="content"> 1005On C++03 compilers, the return value is of an unspecified type. 1006</td> 1007</tr> 1008</table> 1009</div> 1010</div> 1011<div class="sect3"> 1012<h4 id="scoped_ptr_swap">swap</h4> 1013<div class="literalblock"> 1014<div class="content"> 1015<pre>void swap(scoped_ptr & b) noexcept;</pre> 1016</div> 1017</div> 1018<div class="paragraph"> 1019<p>Exchanges the contents of the two smart pointers. <code>T</code> need not be a complete type.</p> 1020</div> 1021</div> 1022</div> 1023<div class="sect2"> 1024<h3 id="scoped_ptr_free_functions">Free Functions</h3> 1025<div class="sect3"> 1026<h4 id="scoped_ptr_swap_2">swap</h4> 1027<div class="literalblock"> 1028<div class="content"> 1029<pre>template<class T> void swap(scoped_ptr<T> & a, scoped_ptr<T> & b) noexcept;</pre> 1030</div> 1031</div> 1032<div class="paragraph"> 1033<p>Equivalent to <code>a.swap(b)</code>.</p> 1034</div> 1035</div> 1036<div class="sect3"> 1037<h4 id="scoped_ptr_comparisons">comparisons</h4> 1038<div class="literalblock"> 1039<div class="content"> 1040<pre>template<class T> bool operator==( scoped_ptr<T> const & p, std::nullptr_t ) noexcept;</pre> 1041</div> 1042</div> 1043<div class="literalblock"> 1044<div class="content"> 1045<pre>template<class T> bool operator==( std::nullptr_t, scoped_ptr<T> const & p ) noexcept;</pre> 1046</div> 1047</div> 1048<div class="paragraph"> 1049<p>Returns <code>p.get() == nullptr</code>.</p> 1050</div> 1051<div class="literalblock"> 1052<div class="content"> 1053<pre>template<class T> bool operator!=( scoped_ptr<T> const & p, std::nullptr_t ) noexcept;</pre> 1054</div> 1055</div> 1056<div class="literalblock"> 1057<div class="content"> 1058<pre>template<class T> bool operator!=( std::nullptr_t, scoped_ptr<T> const & p ) noexcept;</pre> 1059</div> 1060</div> 1061<div class="paragraph"> 1062<p>Returns <code>p.get() != nullptr</code>.</p> 1063</div> 1064</div> 1065</div> 1066<div class="sect2"> 1067<h3 id="scoped_ptr_example">Example</h3> 1068<div class="paragraph"> 1069<p>Here’s an example that uses <code>scoped_ptr</code>.</p> 1070</div> 1071<div class="listingblock"> 1072<div class="content"> 1073<pre class="highlight"><code>#include <boost/scoped_ptr.hpp> 1074#include <iostream> 1075 1076struct Shoe { ~Shoe() { std::cout << "Buckle my shoe\n"; } }; 1077 1078class MyClass { 1079 boost::scoped_ptr<int> ptr; 1080 public: 1081 MyClass() : ptr(new int) { *ptr = 0; } 1082 int add_one() { return ++*ptr; } 1083}; 1084 1085int main() 1086{ 1087 boost::scoped_ptr<Shoe> x(new Shoe); 1088 MyClass my_instance; 1089 std::cout << my_instance.add_one() << '\n'; 1090 std::cout << my_instance.add_one() << '\n'; 1091}</code></pre> 1092</div> 1093</div> 1094<div class="paragraph"> 1095<p>The example program produces the beginning of a child’s nursery rhyme:</p> 1096</div> 1097<div class="listingblock"> 1098<div class="content"> 1099<pre class="highlight"><code>1 11002 1101Buckle my shoe</code></pre> 1102</div> 1103</div> 1104</div> 1105<div class="sect2"> 1106<h3 id="scoped_ptr_rationale">Rationale</h3> 1107<div class="paragraph"> 1108<p>The primary reason to use <code>scoped_ptr</code> rather than <code>std::auto_ptr</code> or <code>std::unique_ptr</code> is to let readers of your code 1109know that you intend "resource acquisition is initialization" to be applied only for the current scope, and have no intent to transfer ownership.</p> 1110</div> 1111<div class="paragraph"> 1112<p>A secondary reason to use <code>scoped_ptr</code> is to prevent a later maintenance programmer from adding a function that transfers 1113ownership by returning the <code>auto_ptr</code>, because the maintenance programmer saw <code>auto_ptr</code>, and assumed ownership could safely be transferred.</p> 1114</div> 1115<div class="paragraph"> 1116<p>Think of <code>bool</code> vs <code>int</code>. We all know that under the covers <code>bool</code> is usually just an <code>int</code>. Indeed, some argued against including bool in the C++ 1117standard because of that. But by coding <code>bool</code> rather than <code>int</code>, you tell your readers what your intent is. Same with <code>scoped_ptr</code>; by using it you are signaling intent.</p> 1118</div> 1119<div class="paragraph"> 1120<p>It has been suggested that <code>scoped_ptr<T></code> is equivalent to <code>std::auto_ptr<T> const</code>. Ed Brey pointed out, however, that <code>reset</code> will not work on a <code>std::auto_ptr<T> const</code>.</p> 1121</div> 1122</div> 1123<div class="sect2"> 1124<h3 id="scoped_ptr_handlebody_idiom">Handle/Body Idiom</h3> 1125<div class="paragraph"> 1126<p>One common usage of <code>scoped_ptr</code> is to implement a handle/body (also called pimpl) idiom which avoids exposing the body (implementation) in the header file.</p> 1127</div> 1128<div class="paragraph"> 1129<p>The <code><a href="../../example/scoped_ptr_example_test.cpp">scoped_ptr_example_test.cpp</a></code> sample program includes a header file, 1130<code><a href="../../example/scoped_ptr_example.hpp">scoped_ptr_example.hpp</a></code>, which uses a <code>scoped_ptr<></code> to an incomplete type to hide the 1131implementation. The instantiation of member functions which require a complete type occurs in the <code><a href="../../example/scoped_ptr_example.cpp">scoped_ptr_example.cpp</a></code> 1132implementation file.</p> 1133</div> 1134</div> 1135<div class="sect2"> 1136<h3 id="scoped_ptr_frequently_asked_questions">Frequently Asked Questions</h3> 1137<div class="qlist qanda"> 1138<ol> 1139<li> 1140<p><em>Why doesn’t <code>scoped_ptr</code> have a <code>release()</code> member?</em></p> 1141<p>When reading source code, it is valuable to be able to draw conclusions about program behavior based on the types being used. If <code>scoped_ptr</code> had a <code>release()</code> member, 1142it would become possible to transfer ownership of the held pointer, weakening its role as a way of limiting resource lifetime to a given context. Use <code>std::auto_ptr</code> where 1143transfer of ownership is required. (supplied by Dave Abrahams)</p> 1144</li> 1145</ol> 1146</div> 1147</div> 1148</div> 1149</div> 1150<div class="sect1"> 1151<h2 id="scoped_array">scoped_array: Scoped Array Ownership</h2> 1152<div class="sectionbody"> 1153<div class="sect2"> 1154<h3 id="scoped_array_description">Description</h3> 1155<div class="paragraph"> 1156<p>The <code>scoped_array</code> class template stores a pointer to a dynamically allocated array. 1157(Dynamically allocated arrays are allocated with the C++ <code>new[]</code> expression.) The array 1158pointed to is guaranteed to be deleted, either on destruction of the <code>scoped_array</code>, 1159or via an explicit <code>reset</code>.</p> 1160</div> 1161<div class="paragraph"> 1162<p>The <code>scoped_array</code> template is a simple solution for simple needs. It supplies a basic 1163"resource acquisition is initialization" facility, without shared-ownership or 1164transfer-of-ownership semantics. Both its name and enforcement of semantics 1165(by being noncopyable) signal its intent to retain ownership solely within the current scope. 1166Because it is noncopyable, it is safer than <code>shared_ptr<T[]></code> for pointers which should not be copied.</p> 1167</div> 1168<div class="paragraph"> 1169<p>Because <code>scoped_array</code> is so simple, in its usual implementation every operation is as fast as a 1170built-in array pointer and it has no more space overhead that a built-in array pointer.</p> 1171</div> 1172<div class="paragraph"> 1173<p>It cannot be used in C++ standard library containers. See <code>shared_ptr<T[]></code> if <code>scoped_array</code> 1174does not meet your needs.</p> 1175</div> 1176<div class="paragraph"> 1177<p>It cannot correctly hold a pointer to a single object. See <code>scoped_ptr</code> for that usage.</p> 1178</div> 1179<div class="paragraph"> 1180<p><code>std::vector</code> is an alternative to <code>scoped_array</code> that is a bit heavier duty but far more flexible. 1181<code>boost::array</code> is an alternative that does not use dynamic allocation.</p> 1182</div> 1183<div class="paragraph"> 1184<p>The class template is parameterized on <code>T</code>, the type of the object pointed to.</p> 1185</div> 1186</div> 1187<div class="sect2"> 1188<h3 id="scoped_array_synopsis">Synopsis</h3> 1189<div class="paragraph"> 1190<p><code>scoped_array</code> is defined in <code><boost/smart_ptr/scoped_array.hpp></code>.</p> 1191</div> 1192<div class="listingblock"> 1193<div class="content"> 1194<pre class="highlight"><code>namespace boost { 1195 1196 template<class T> class scoped_array { 1197 private: 1198 1199 scoped_array(scoped_array const &); 1200 scoped_array & operator=(scoped_array const &); 1201 1202 void operator==( scoped_array const& ) const; 1203 void operator!=( scoped_array const& ) const; 1204 1205 public: 1206 1207 typedef T element_type; 1208 1209 explicit scoped_array(T * p = 0) noexcept; 1210 ~scoped_array() noexcept; 1211 1212 void reset(T * p = 0) noexcept; 1213 1214 T & operator[](std::ptrdiff_t i) const noexcept; 1215 T * get() const noexcept; 1216 1217 explicit operator bool () const noexcept; 1218 1219 void swap(scoped_array & b) noexcept; 1220 }; 1221 1222 template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b) noexcept; 1223 1224 template<class T> 1225 bool operator==( scoped_array<T> const & p, std::nullptr_t ) noexcept; 1226 template<class T> 1227 bool operator==( std::nullptr_t, scoped_array<T> const & p ) noexcept; 1228 1229 template<class T> 1230 bool operator!=( scoped_array<T> const & p, std::nullptr_t ) noexcept; 1231 template<class T> 1232 bool operator!=( std::nullptr_t, scoped_array<T> const & p ) noexcept; 1233}</code></pre> 1234</div> 1235</div> 1236</div> 1237<div class="sect2"> 1238<h3 id="scoped_array_members">Members</h3> 1239<div class="sect3"> 1240<h4 id="scoped_array_element_type">element_type</h4> 1241<div class="literalblock"> 1242<div class="content"> 1243<pre>typedef T element_type;</pre> 1244</div> 1245</div> 1246<div class="paragraph"> 1247<p>Provides the type of the stored pointer.</p> 1248</div> 1249</div> 1250<div class="sect3"> 1251<h4 id="scoped_array_constructors">constructors</h4> 1252<div class="literalblock"> 1253<div class="content"> 1254<pre>explicit scoped_array(T * p = 0) noexcept;</pre> 1255</div> 1256</div> 1257<div class="paragraph"> 1258<p>Constructs a <code>scoped_array</code>, storing a copy of <code>p</code>, which must have been 1259allocated via a C++ <code>new[]</code> expression or be 0. <code>T</code> is not required be a complete type.</p> 1260</div> 1261</div> 1262<div class="sect3"> 1263<h4 id="scoped_array_destructor">destructor</h4> 1264<div class="literalblock"> 1265<div class="content"> 1266<pre>~scoped_array() noexcept;</pre> 1267</div> 1268</div> 1269<div class="paragraph"> 1270<p>Deletes the array pointed to by the stored pointer. Note that <code>delete[]</code> on a pointer with 1271a value of 0 is harmless. <code>T</code> must be complete, and <code>delete[]</code> on the stored pointer must 1272not throw exceptions.</p> 1273</div> 1274</div> 1275<div class="sect3"> 1276<h4 id="scoped_array_reset">reset</h4> 1277<div class="literalblock"> 1278<div class="content"> 1279<pre>void reset(T * p = 0) noexcept;</pre> 1280</div> 1281</div> 1282<div class="paragraph"> 1283<p>Deletes the array pointed to by the stored pointer and then stores a copy of <code>p</code>, 1284which must have been allocated via a C++ <code>new[]</code> expression or be 0. <code>T</code> must be complete, 1285and <code>delete[]</code> on the stored pointer must not throw exceptions.</p> 1286</div> 1287</div> 1288<div class="sect3"> 1289<h4 id="scoped_array_subscripting">subscripting</h4> 1290<div class="literalblock"> 1291<div class="content"> 1292<pre>T & operator[](std::ptrdiff_t i) const noexcept;</pre> 1293</div> 1294</div> 1295<div class="paragraph"> 1296<p>Returns a reference to element <code>i</code> of the array pointed to by the stored pointer. 1297Behavior is undefined and almost certainly undesirable if the stored pointer is 0, 1298or if <code>i</code> is less than 0 or is greater than or equal to the number of elements in 1299the array.</p> 1300</div> 1301</div> 1302<div class="sect3"> 1303<h4 id="scoped_array_get">get</h4> 1304<div class="literalblock"> 1305<div class="content"> 1306<pre>T * get() const noexcept;</pre> 1307</div> 1308</div> 1309<div class="paragraph"> 1310<p>Returns the stored pointer. <code>T</code> need not be a complete type.</p> 1311</div> 1312</div> 1313<div class="sect3"> 1314<h4 id="scoped_array_conversions">conversions</h4> 1315<div class="literalblock"> 1316<div class="content"> 1317<pre>explicit operator bool () const noexcept;</pre> 1318</div> 1319</div> 1320<div class="paragraph"> 1321<p>Returns <code>get() != 0</code>.</p> 1322</div> 1323<div class="admonitionblock note"> 1324<table> 1325<tr> 1326<td class="icon"> 1327<div class="title">Note</div> 1328</td> 1329<td class="content"> 1330On C++03 compilers, the return value is of an unspecified type. 1331</td> 1332</tr> 1333</table> 1334</div> 1335</div> 1336<div class="sect3"> 1337<h4 id="scoped_array_swap">swap</h4> 1338<div class="literalblock"> 1339<div class="content"> 1340<pre>void swap(scoped_array & b) noexcept;</pre> 1341</div> 1342</div> 1343<div class="paragraph"> 1344<p>Exchanges the contents of the two smart pointers. <code>T</code> need not be a complete type.</p> 1345</div> 1346</div> 1347</div> 1348<div class="sect2"> 1349<h3 id="scoped_array_free_functions">Free Functions</h3> 1350<div class="sect3"> 1351<h4 id="scoped_array_swap_2">swap</h4> 1352<div class="literalblock"> 1353<div class="content"> 1354<pre>template<class T> void swap(scoped_array<T> & a, scoped_array<T> & b) noexcept;</pre> 1355</div> 1356</div> 1357<div class="paragraph"> 1358<p>Equivalent to <code>a.swap(b)</code>.</p> 1359</div> 1360</div> 1361<div class="sect3"> 1362<h4 id="scoped_array_comparisons">comparisons</h4> 1363<div class="literalblock"> 1364<div class="content"> 1365<pre>template<class T> 1366 bool operator==( scoped_array<T> const & p, std::nullptr_t ) noexcept;</pre> 1367</div> 1368</div> 1369<div class="literalblock"> 1370<div class="content"> 1371<pre>template<class T> 1372 bool operator==( std::nullptr_t, scoped_array<T> const & p ) noexcept;</pre> 1373</div> 1374</div> 1375<div class="paragraph"> 1376<p>Returns <code>p.get() == nullptr</code>.</p> 1377</div> 1378<div class="literalblock"> 1379<div class="content"> 1380<pre>template<class T> 1381 bool operator!=( scoped_array<T> const & p, std::nullptr_t ) noexcept;</pre> 1382</div> 1383</div> 1384<div class="literalblock"> 1385<div class="content"> 1386<pre>template<class T> 1387 bool operator!=( std::nullptr_t, scoped_array<T> const & p ) noexcept;</pre> 1388</div> 1389</div> 1390<div class="paragraph"> 1391<p>Returns <code>p.get() != nullptr</code>.</p> 1392</div> 1393</div> 1394</div> 1395</div> 1396</div> 1397<div class="sect1"> 1398<h2 id="shared_ptr">shared_ptr: Shared Ownership</h2> 1399<div class="sectionbody"> 1400<div class="sect2"> 1401<h3 id="shared_ptr_description">Description</h3> 1402<div class="paragraph"> 1403<p>The <code>shared_ptr</code> class template stores a pointer to a dynamically allocated object, typically with a C++ <code>new</code>-expression. 1404The object pointed to is guaranteed to be deleted when the last <code>shared_ptr</code> pointing to it is destroyed or reset.</p> 1405</div> 1406<div class="listingblock"> 1407<div class="title">Code Example 1. Using shared_ptr</div> 1408<div class="content"> 1409<pre class="highlight"><code>shared_ptr<X> p1( new X ); 1410shared_ptr<void> p2( new int(5) );</code></pre> 1411</div> 1412</div> 1413<div class="paragraph"> 1414<p><code>shared_ptr</code> deletes the exact pointer that has been passed at construction time, complete with its original type, regardless 1415of the template parameter. In the second example above, when <code>p2</code> is destroyed or reset, it will call <code>delete</code> on the original 1416<code>int*</code> that has been passed to the constructor, even though <code>p2</code> itself is of type <code>shared_ptr<void></code> and stores a pointer of 1417type <code>void*</code>.</p> 1418</div> 1419<div class="paragraph"> 1420<p>Every <code>shared_ptr</code> meets the <code>CopyConstructible</code>, <code>MoveConstructible</code>, <code>CopyAssignable</code> and <code>MoveAssignable</code> requirements of the 1421C++ Standard Library, and can be used in standard library containers. Comparison operators are supplied so that <code>shared_ptr</code> 1422works with the standard library’s associative containers.</p> 1423</div> 1424<div class="paragraph"> 1425<p>Because the implementation uses reference counting, cycles of <code>shared_ptr</code> instances will not be reclaimed. For example, if <code>main()</code> 1426holds a <code>shared_ptr</code> to <code>A</code>, which directly or indirectly holds a <code>shared_ptr</code> back to <code>A</code>, <code>A’s use count will be 2. Destruction 1427of the original `shared_ptr</code> will leave <code>A</code> dangling with a use count of 1. Use <code><a href="#weak_ptr">weak_ptr</a></code> to "break cycles."</p> 1428</div> 1429<div class="paragraph"> 1430<p>The class template is parameterized on <code>T</code>, the type of the object pointed to. <code>shared_ptr</code> and most of its member functions place 1431no requirements on <code>T</code>; it is allowed to be an incomplete type, or <code>void</code>. Member functions that do place additional requirements 1432(constructors, <code>reset</code>) are explicitly documented below.</p> 1433</div> 1434<div class="paragraph"> 1435<p><code>shared_ptr<T></code> can be implicitly converted to <code>shared_ptr<U></code> whenever <code>T*</code> can be implicitly converted to <code>U*</code>. In particular, 1436<code>shared_ptr<T></code> is implicitly convertible to <code>shared_ptr<T const></code>, to <code>shared_ptr<U></code> where <code>U</code> is an accessible base of <code>T</code>, 1437and to <code>shared_ptr<void></code>.</p> 1438</div> 1439<div class="paragraph"> 1440<p><code>shared_ptr</code> is now part of the C++11 Standard, as <code>std::shared_ptr</code>.</p> 1441</div> 1442<div class="paragraph"> 1443<p>Starting with Boost release 1.53, <code>shared_ptr</code> can be used to hold a pointer to a dynamically allocated array. This is accomplished 1444by using an array type (<code>T[]</code> or <code>T[N]</code>) as the template parameter. There is almost no difference between using an unsized array, 1445<code>T[]</code>, and a sized array, <code>T[N]</code>; the latter just enables <code>operator[]</code> to perform a range check on the index.</p> 1446</div> 1447<div class="listingblock"> 1448<div class="title">Code Example 2. Using shared_ptr with arrays</div> 1449<div class="content"> 1450<pre class="highlight"><code>shared_ptr<double[1024]> p1( new double[1024] ); 1451shared_ptr<double[]> p2( new double[n] );</code></pre> 1452</div> 1453</div> 1454</div> 1455<div class="sect2"> 1456<h3 id="shared_ptr_best_practices">Best Practices</h3> 1457<div class="paragraph"> 1458<p>A simple guideline that nearly eliminates the possibility of memory leaks is: always use a named smart pointer variable to hold the result 1459of <code>new</code>. Every occurence of the <code>new</code> keyword in the code should have the form:</p> 1460</div> 1461<div class="literalblock"> 1462<div class="content"> 1463<pre>shared_ptr<T> p(new Y);</pre> 1464</div> 1465</div> 1466<div class="paragraph"> 1467<p>It is, of course, acceptable to use another smart pointer in place of <code>shared_ptr</code> above; having <code>T</code> and <code>Y</code> be the same type, or passing 1468arguments to the constructor of <code>Y</code> is also OK.</p> 1469</div> 1470<div class="paragraph"> 1471<p>If you observe this guideline, it naturally follows that you will have no explicit <code>delete</code> statements; <code>try</code>/<code>catch</code> constructs will be rare.</p> 1472</div> 1473<div class="paragraph"> 1474<p>Avoid using unnamed <code>shared_ptr</code> temporaries to save typing; to see why this is dangerous, consider this example:</p> 1475</div> 1476<div class="listingblock"> 1477<div class="title">Code Example 3. Exception-safe and -unsafe use of shared_ptr</div> 1478<div class="content"> 1479<pre class="highlight"><code>void f(shared_ptr<int>, int); 1480int g(); 1481 1482void ok() 1483{ 1484 shared_ptr<int> p( new int(2) ); 1485 f( p, g() ); 1486} 1487 1488void bad() 1489{ 1490 f( shared_ptr<int>( new int(2) ), g() ); 1491}</code></pre> 1492</div> 1493</div> 1494<div class="paragraph"> 1495<p>The function <code>ok</code> follows the guideline to the letter, whereas <code>bad</code> constructs the temporary <code>shared_ptr</code> in place, admitting the possibility of 1496a memory leak. Since function arguments are evaluated in unspecified order, it is possible for <code>new int(2)</code> to be evaluated first, <code>g()</code> second, 1497and we may never get to the <code>shared_ptr</code> constructor if <code>g</code> throws an exception. See <a href="http://www.gotw.ca/gotw/056.htm">Herb Sutter’s treatment</a> of 1498the issue for more information.</p> 1499</div> 1500<div class="paragraph"> 1501<p>The exception safety problem described above may also be eliminated by using the <code><a href="#make_shared">make_shared</a></code> or <code>allocate_shared</code> factory 1502functions defined in <code><boost/smart_ptr/make_shared.hpp></code>. These factory functions also provide an efficiency benefit by consolidating allocations.</p> 1503</div> 1504</div> 1505<div class="sect2"> 1506<h3 id="shared_ptr_synopsis">Synopsis</h3> 1507<div class="paragraph"> 1508<p><code>shared_ptr</code> is defined in <code><boost/smart_ptr/shared_ptr.hpp></code>.</p> 1509</div> 1510<div class="listingblock"> 1511<div class="content"> 1512<pre class="highlight"><code>namespace boost { 1513 1514 class bad_weak_ptr: public std::exception; 1515 1516 template<class T> class weak_ptr; 1517 1518 template<class T> class shared_ptr { 1519 public: 1520 1521 typedef /*see below*/ element_type; 1522 1523 constexpr shared_ptr() noexcept; 1524 constexpr shared_ptr(std::nullptr_t) noexcept; 1525 1526 template<class Y> explicit shared_ptr(Y * p); 1527 template<class Y, class D> shared_ptr(Y * p, D d); 1528 template<class Y, class D, class A> shared_ptr(Y * p, D d, A a); 1529 template<class D> shared_ptr(std::nullptr_t p, D d); 1530 template<class D, class A> shared_ptr(std::nullptr_t p, D d, A a); 1531 1532 ~shared_ptr() noexcept; 1533 1534 shared_ptr(shared_ptr const & r) noexcept; 1535 template<class Y> shared_ptr(shared_ptr<Y> const & r) noexcept; 1536 1537 shared_ptr(shared_ptr && r) noexcept; 1538 template<class Y> shared_ptr(shared_ptr<Y> && r) noexcept; 1539 1540 template<class Y> shared_ptr(shared_ptr<Y> const & r, element_type * p) noexcept; 1541 template<class Y> shared_ptr(shared_ptr<Y> && r, element_type * p) noexcept; 1542 1543 template<class Y> explicit shared_ptr(weak_ptr<Y> const & r); 1544 1545 template<class Y> explicit shared_ptr(std::auto_ptr<Y> & r); 1546 template<class Y> shared_ptr(std::auto_ptr<Y> && r); 1547 1548 template<class Y, class D> shared_ptr(std::unique_ptr<Y, D> && r); 1549 1550 shared_ptr & operator=(shared_ptr const & r) noexcept; 1551 template<class Y> shared_ptr & operator=(shared_ptr<Y> const & r) noexcept; 1552 1553 shared_ptr & operator=(shared_ptr const && r) noexcept; 1554 template<class Y> shared_ptr & operator=(shared_ptr<Y> const && r) noexcept; 1555 1556 template<class Y> shared_ptr & operator=(std::auto_ptr<Y> & r); 1557 template<class Y> shared_ptr & operator=(std::auto_ptr<Y> && r); 1558 1559 template<class Y, class D> shared_ptr & operator=(std::unique_ptr<Y, D> && r); 1560 1561 shared_ptr & operator=(std::nullptr_t) noexcept; 1562 1563 void reset() noexcept; 1564 1565 template<class Y> void reset(Y * p); 1566 template<class Y, class D> void reset(Y * p, D d); 1567 template<class Y, class D, class A> void reset(Y * p, D d, A a); 1568 1569 template<class Y> void reset(shared_ptr<Y> const & r, element_type * p) noexcept; 1570 template<class Y> void reset(shared_ptr<Y> && r, element_type * p) noexcept; 1571 1572 T & operator*() const noexcept; // only valid when T is not an array type 1573 T * operator->() const noexcept; // only valid when T is not an array type 1574 1575 // only valid when T is an array type 1576 element_type & operator[](std::ptrdiff_t i) const noexcept; 1577 1578 element_type * get() const noexcept; 1579 1580 bool unique() const noexcept; 1581 long use_count() const noexcept; 1582 1583 explicit operator bool() const noexcept; 1584 1585 void swap(shared_ptr & b) noexcept; 1586 1587 template<class Y> bool owner_before(shared_ptr<Y> const & r) const noexcept; 1588 template<class Y> bool owner_before(weak_ptr<Y> const & r) const noexcept; 1589 1590 template<class Y> bool owner_equals(shared_ptr<Y> const & r) const noexcept; 1591 template<class Y> bool owner_equals(weak_ptr<Y> const & r) const noexcept; 1592 1593 std::size_t owner_hash_value() const noexcept; 1594 }; 1595 1596 template<class T, class U> 1597 bool operator==(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 1598 1599 template<class T, class U> 1600 bool operator!=(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 1601 1602 template<class T, class U> 1603 bool operator<(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 1604 1605 template<class T> bool operator==(shared_ptr<T> const & p, std::nullptr_t) noexcept; 1606 template<class T> bool operator==(std::nullptr_t, shared_ptr<T> const & p) noexcept; 1607 1608 template<class T> bool operator!=(shared_ptr<T> const & p, std::nullptr_t) noexcept; 1609 template<class T> bool operator!=(std::nullptr_t, shared_ptr<T> const & p) noexcept; 1610 1611 template<class T> void swap(shared_ptr<T> & a, shared_ptr<T> & b) noexcept; 1612 1613 template<class T> 1614 typename shared_ptr<T>::element_type * 1615 get_pointer(shared_ptr<T> const & p) noexcept; 1616 1617 template<class T, class U> 1618 shared_ptr<T> static_pointer_cast(shared_ptr<U> const & r) noexcept; 1619 1620 template<class T, class U> 1621 shared_ptr<T> const_pointer_cast(shared_ptr<U> const & r) noexcept; 1622 1623 template<class T, class U> 1624 shared_ptr<T> dynamic_pointer_cast(shared_ptr<U> const & r) noexcept; 1625 1626 template<class T, class U> 1627 shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U> const & r) noexcept; 1628 1629 template<class E, class T, class Y> 1630 std::basic_ostream<E, T> & 1631 operator<< (std::basic_ostream<E, T> & os, shared_ptr<Y> const & p); 1632 1633 template<class D, class T> D * get_deleter(shared_ptr<T> const & p) noexcept; 1634 1635 template<class T> bool atomic_is_lock_free( shared_ptr<T> const * p ) noexcept; 1636 1637 template<class T> shared_ptr<T> atomic_load( shared_ptr<T> const * p ) noexcept; 1638 template<class T> 1639 shared_ptr<T> atomic_load_explicit( shared_ptr<T> const * p, int ) noexcept; 1640 1641 template<class T> 1642 void atomic_store( shared_ptr<T> * p, shared_ptr<T> r ) noexcept; 1643 template<class T> 1644 void atomic_store_explicit( shared_ptr<T> * p, shared_ptr<T> r, int ) noexcept; 1645 1646 template<class T> 1647 shared_ptr<T> atomic_exchange( shared_ptr<T> * p, shared_ptr<T> r ) noexcept; 1648 template<class T> 1649 shared_ptr<T> atomic_exchange_explicit( 1650 shared_ptr<T> * p, shared_ptr<T> r, int ) noexcept; 1651 1652 template<class T> 1653 bool atomic_compare_exchange( 1654 shared_ptr<T> * p, shared_ptr<T> * v, shared_ptr<T> w ) noexcept; 1655 template<class T> 1656 bool atomic_compare_exchange_explicit( 1657 shared_ptr<T> * p, shared_ptr<T> * v, shared_ptr<T> w, int, int ) noexcept; 1658}</code></pre> 1659</div> 1660</div> 1661</div> 1662<div class="sect2"> 1663<h3 id="shared_ptr_members">Members</h3> 1664<div class="sect3"> 1665<h4 id="shared_ptr_element_type">element_type</h4> 1666<div class="listingblock"> 1667<div class="content"> 1668<pre class="highlight"><code>typedef ... element_type;</code></pre> 1669</div> 1670</div> 1671<div class="paragraph"> 1672<p><code>element_type</code> is <code>T</code> when <code>T</code> is not an array type, and <code>U</code> when <code>T</code> is <code>U[]</code> or <code>U[N]</code>.</p> 1673</div> 1674</div> 1675<div class="sect3"> 1676<h4 id="shared_ptr_default_constructor">default constructor</h4> 1677<div class="listingblock"> 1678<div class="content"> 1679<pre class="highlight"><code>constexpr shared_ptr() noexcept;</code></pre> 1680</div> 1681</div> 1682<div class="listingblock"> 1683<div class="content"> 1684<pre class="highlight"><code>constexpr shared_ptr(std::nullptr_t) noexcept;</code></pre> 1685</div> 1686</div> 1687<div class="ulist none"> 1688<ul class="none"> 1689<li> 1690<p></p> 1691<div class="dlist"> 1692<dl> 1693<dt class="hdlist1">Effects</dt> 1694<dd> 1695<p>Constructs an empty <code>shared_ptr</code>.</p> 1696</dd> 1697<dt class="hdlist1">Postconditions</dt> 1698<dd> 1699<p><code>use_count() == 0 && get() == 0</code>.</p> 1700</dd> 1701</dl> 1702</div> 1703</li> 1704</ul> 1705</div> 1706</div> 1707<div class="sect3"> 1708<h4 id="shared_ptr_pointer_constructor">pointer constructor</h4> 1709<div class="listingblock"> 1710<div class="content"> 1711<pre class="highlight"><code>template<class Y> explicit shared_ptr(Y * p);</code></pre> 1712</div> 1713</div> 1714<div class="ulist none"> 1715<ul class="none"> 1716<li> 1717<p></p> 1718<div class="dlist"> 1719<dl> 1720<dt class="hdlist1">Requires</dt> 1721<dd> 1722<p><code>Y</code> must be a complete type. The expression <code>delete[] p</code>, when <code>T</code> is an array type, or <code>delete p</code>, when <code>T</code> is not an array type, 1723must be well-formed, well-defined, and not throw exceptions. When <code>T</code> is <code>U[N]</code>, <code>Y(*)[N]</code> must be convertible to <code>T*</code>; when <code>T</code> is <code>U[]</code>, <code>Y(*)[]</code> 1724must be convertible to <code>T*</code>; otherwise, <code>Y*</code> must be convertible to <code>T*</code>.</p> 1725</dd> 1726<dt class="hdlist1">Effects</dt> 1727<dd> 1728<p>When <code>T</code> is not an array type, constructs a <code>shared_ptr</code> that owns the pointer <code>p</code>. Otherwise, constructs a <code>shared_ptr</code> that owns <code>p</code> and 1729a deleter of an unspecified type that calls <code>delete[] p</code>.</p> 1730</dd> 1731<dt class="hdlist1">Postconditions</dt> 1732<dd> 1733<p><code>use_count() == 1 && get() == p</code>. If <code>T</code> is not an array type and <code>p</code> is unambiguously convertible to <code>enable_shared_from_this<V>*</code> 1734for some <code>V</code>, <code>p->shared_from_this()</code> returns a copy of <code>*this</code>.</p> 1735</dd> 1736<dt class="hdlist1">Throws</dt> 1737<dd> 1738<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 1739</dd> 1740<dt class="hdlist1">Exception safety</dt> 1741<dd> 1742<p>If an exception is thrown, the constructor calls <code>delete[] p</code>, when <code>T</code> is an array type, or <code>delete p</code>, when <code>T</code> is not an array type.</p> 1743</dd> 1744</dl> 1745</div> 1746</li> 1747</ul> 1748</div> 1749<div class="admonitionblock note"> 1750<table> 1751<tr> 1752<td class="icon"> 1753<div class="title">Note</div> 1754</td> 1755<td class="content"> 1756<code>p</code> must be a pointer to an object that was allocated via a C++ <code>new</code> expression or be 0. The postcondition that use count is 1 holds even if <code>p</code> 1757is 0; invoking <code>delete</code> on a pointer that has a value of 0 is harmless. 1758</td> 1759</tr> 1760</table> 1761</div> 1762<div class="admonitionblock note"> 1763<table> 1764<tr> 1765<td class="icon"> 1766<div class="title">Note</div> 1767</td> 1768<td class="content"> 1769This constructor is a template in order to remember the actual pointer type passed. The destructor will call delete with the same pointer, complete 1770with its original type, even when <code>T</code> does not have a virtual destructor, or is <code>void</code>. 1771</td> 1772</tr> 1773</table> 1774</div> 1775</div> 1776<div class="sect3"> 1777<h4 id="shared_ptr_constructors_taking_a_deleter">constructors taking a deleter</h4> 1778<div class="listingblock"> 1779<div class="content"> 1780<pre class="highlight"><code>template<class Y, class D> shared_ptr(Y * p, D d);</code></pre> 1781</div> 1782</div> 1783<div class="listingblock"> 1784<div class="content"> 1785<pre class="highlight"><code>template<class Y, class D, class A> shared_ptr(Y * p, D d, A a);</code></pre> 1786</div> 1787</div> 1788<div class="listingblock"> 1789<div class="content"> 1790<pre class="highlight"><code>template<class D> shared_ptr(std::nullptr_t p, D d);</code></pre> 1791</div> 1792</div> 1793<div class="listingblock"> 1794<div class="content"> 1795<pre class="highlight"><code>template<class D, class A> shared_ptr(std::nullptr_t p, D d, A a);</code></pre> 1796</div> 1797</div> 1798<div class="ulist none"> 1799<ul class="none"> 1800<li> 1801<p></p> 1802<div class="dlist"> 1803<dl> 1804<dt class="hdlist1">Requires</dt> 1805<dd> 1806<p><code>D</code> must be <code>CopyConstructible</code>. The copy constructor and destructor of <code>D</code> must not throw. The expression <code>d(p)</code> must be well-formed, well-defined, 1807and not throw exceptions. <code>A</code> must be an <code>Allocator</code>, as described in section Allocator Requirements [allocator.requirements] of the C++ Standard. 1808When <code>T</code> is <code>U[N]</code>, <code>Y(*)[N]</code> must be convertible to <code>T*</code>; when <code>T</code> is <code>U[]</code>, <code>Y(*)[]</code> must be convertible to <code>T*</code>; otherwise, <code>Y*</code> must be convertible to <code>T*</code>.</p> 1809</dd> 1810<dt class="hdlist1">Effects</dt> 1811<dd> 1812<p>Constructs a <code>shared_ptr</code> that owns the pointer <code>p</code> and the deleter <code>d</code>. The constructors taking an allocator a allocate memory using a copy of <code>a</code>.</p> 1813</dd> 1814<dt class="hdlist1">Postconditions</dt> 1815<dd> 1816<p><code>use_count() == 1 && get() == p</code>. If <code>T</code> is not an array type and <code>p</code> is unambiguously convertible to <code>enable_shared_from_this<V>*</code> for some <code>V</code>, 1817<code>p->shared_from_this()</code> returns a copy of <code>*this</code>.</p> 1818</dd> 1819<dt class="hdlist1">Throws</dt> 1820<dd> 1821<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 1822</dd> 1823<dt class="hdlist1">Exception safety</dt> 1824<dd> 1825<p>If an exception is thrown, <code>d(p)</code> is called.</p> 1826</dd> 1827</dl> 1828</div> 1829</li> 1830</ul> 1831</div> 1832<div class="admonitionblock note"> 1833<table> 1834<tr> 1835<td class="icon"> 1836<div class="title">Note</div> 1837</td> 1838<td class="content"> 1839When the the time comes to delete the object pointed to by <code>p</code>, the stored copy of <code>d</code> is invoked with the stored copy of <code>p</code> as an argument. 1840</td> 1841</tr> 1842</table> 1843</div> 1844<div class="admonitionblock note"> 1845<table> 1846<tr> 1847<td class="icon"> 1848<div class="title">Note</div> 1849</td> 1850<td class="content"> 1851Custom deallocators allow a factory function returning a <code>shared_ptr</code> to insulate the user from its memory allocation strategy. Since the deallocator 1852is not part of the type, changing the allocation strategy does not break source or binary compatibility, and does not require a client recompilation. For example, 1853a "no-op" deallocator is useful when returning a <code>shared_ptr</code> to a statically allocated object, and other variations allow a <code>shared_ptr</code> to be used as a wrapper 1854for another smart pointer, easing interoperability. 1855</td> 1856</tr> 1857</table> 1858</div> 1859<div class="admonitionblock note"> 1860<table> 1861<tr> 1862<td class="icon"> 1863<div class="title">Note</div> 1864</td> 1865<td class="content"> 1866The requirement that the copy constructor of <code>D</code> does not throw comes from the pass by value. If the copy constructor throws, the pointer would leak. 1867</td> 1868</tr> 1869</table> 1870</div> 1871</div> 1872<div class="sect3"> 1873<h4 id="shared_ptr_copy_and_converting_constructors">copy and converting constructors</h4> 1874<div class="listingblock"> 1875<div class="content"> 1876<pre class="highlight"><code>shared_ptr(shared_ptr const & r) noexcept;</code></pre> 1877</div> 1878</div> 1879<div class="listingblock"> 1880<div class="content"> 1881<pre class="highlight"><code>template<class Y> shared_ptr(shared_ptr<Y> const & r) noexcept;</code></pre> 1882</div> 1883</div> 1884<div class="ulist none"> 1885<ul class="none"> 1886<li> 1887<p></p> 1888<div class="dlist"> 1889<dl> 1890<dt class="hdlist1">Requires</dt> 1891<dd> 1892<p><code>Y*</code> should be convertible to <code>T*</code>.</p> 1893</dd> 1894<dt class="hdlist1">Effects</dt> 1895<dd> 1896<p>If <code>r</code> is empty, constructs an empty <code>shared_ptr</code>; otherwise, constructs a <code>shared_ptr</code> that shares ownership with <code>r</code>.</p> 1897</dd> 1898<dt class="hdlist1">Postconditions</dt> 1899<dd> 1900<p><code>get() == r.get() && use_count() == r.use_count()</code>.</p> 1901</dd> 1902</dl> 1903</div> 1904</li> 1905</ul> 1906</div> 1907</div> 1908<div class="sect3"> 1909<h4 id="shared_ptr_move_constructors">move constructors</h4> 1910<div class="listingblock"> 1911<div class="content"> 1912<pre class="highlight"><code>shared_ptr(shared_ptr && r) noexcept;</code></pre> 1913</div> 1914</div> 1915<div class="listingblock"> 1916<div class="content"> 1917<pre class="highlight"><code>template<class Y> shared_ptr(shared_ptr<Y> && r) noexcept;</code></pre> 1918</div> 1919</div> 1920<div class="ulist none"> 1921<ul class="none"> 1922<li> 1923<p></p> 1924<div class="dlist"> 1925<dl> 1926<dt class="hdlist1">Requires</dt> 1927<dd> 1928<p><code>Y*</code> should be convertible to <code>T*</code>.</p> 1929</dd> 1930<dt class="hdlist1">Effects</dt> 1931<dd> 1932<p>Move-constructs a <code>shared_ptr</code> from <code>r</code>.</p> 1933</dd> 1934<dt class="hdlist1">Postconditions</dt> 1935<dd> 1936<p><code>*this</code> contains the old value of <code>r</code>. <code>r</code> is empty and <code>r.get() == 0</code>.</p> 1937</dd> 1938</dl> 1939</div> 1940</li> 1941</ul> 1942</div> 1943</div> 1944<div class="sect3"> 1945<h4 id="shared_ptr_aliasing_constructor">aliasing constructor</h4> 1946<div class="listingblock"> 1947<div class="content"> 1948<pre class="highlight"><code>template<class Y> shared_ptr(shared_ptr<Y> const & r, element_type * p) noexcept;</code></pre> 1949</div> 1950</div> 1951<div class="ulist none"> 1952<ul class="none"> 1953<li> 1954<p></p> 1955<div class="dlist"> 1956<dl> 1957<dt class="hdlist1">Effects</dt> 1958<dd> 1959<p>Copy-constructs a <code>shared_ptr</code> from <code>r</code>, while storing <code>p</code> instead.</p> 1960</dd> 1961<dt class="hdlist1">Postconditions</dt> 1962<dd> 1963<p><code>get() == p && use_count() == r.use_count()</code>.</p> 1964</dd> 1965</dl> 1966</div> 1967</li> 1968</ul> 1969</div> 1970</div> 1971<div class="sect3"> 1972<h4 id="shared_ptr_aliasing_move_constructor">aliasing move constructor</h4> 1973<div class="listingblock"> 1974<div class="content"> 1975<pre class="highlight"><code>template<class Y> shared_ptr(shared_ptr<Y> && r, element_type * p) noexcept;</code></pre> 1976</div> 1977</div> 1978<div class="ulist none"> 1979<ul class="none"> 1980<li> 1981<p></p> 1982<div class="dlist"> 1983<dl> 1984<dt class="hdlist1">Effects</dt> 1985<dd> 1986<p>Move-constructs a <code>shared_ptr</code> from <code>r</code>, while storing <code>p</code> instead.</p> 1987</dd> 1988<dt class="hdlist1">Postconditions</dt> 1989<dd> 1990<p><code>get() == p</code> and <code>use_count()</code> equals the old count of <code>r</code>. <code>r</code> is empty and <code>r.get() == 0</code>.</p> 1991</dd> 1992</dl> 1993</div> 1994</li> 1995</ul> 1996</div> 1997</div> 1998<div class="sect3"> 1999<h4 id="shared_ptr_weak_ptr_constructor">weak_ptr constructor</h4> 2000<div class="listingblock"> 2001<div class="content"> 2002<pre class="highlight"><code>template<class Y> explicit shared_ptr(weak_ptr<Y> const & r);</code></pre> 2003</div> 2004</div> 2005<div class="ulist none"> 2006<ul class="none"> 2007<li> 2008<p></p> 2009<div class="dlist"> 2010<dl> 2011<dt class="hdlist1">Requires</dt> 2012<dd> 2013<p><code>Y*</code> should be convertible to <code>T*</code>.</p> 2014</dd> 2015<dt class="hdlist1">Effects</dt> 2016<dd> 2017<p>Constructs a <code>shared_ptr</code> that shares ownership with <code>r</code> and stores a copy of the pointer stored in <code>r</code>.</p> 2018</dd> 2019<dt class="hdlist1">Postconditions</dt> 2020<dd> 2021<p><code>use_count() == r.use_count()</code>.</p> 2022</dd> 2023<dt class="hdlist1">Throws</dt> 2024<dd> 2025<p><code>bad_weak_ptr</code> when <code>r.use_count() == 0</code>.</p> 2026</dd> 2027<dt class="hdlist1">Exception safety</dt> 2028<dd> 2029<p>If an exception is thrown, the constructor has no effect.</p> 2030</dd> 2031</dl> 2032</div> 2033</li> 2034</ul> 2035</div> 2036</div> 2037<div class="sect3"> 2038<h4 id="shared_ptr_auto_ptr_constructors">auto_ptr constructors</h4> 2039<div class="listingblock"> 2040<div class="content"> 2041<pre class="highlight"><code>template<class Y> shared_ptr(std::auto_ptr<Y> & r);</code></pre> 2042</div> 2043</div> 2044<div class="listingblock"> 2045<div class="content"> 2046<pre class="highlight"><code>template<class Y> shared_ptr(std::auto_ptr<Y> && r);</code></pre> 2047</div> 2048</div> 2049<div class="ulist none"> 2050<ul class="none"> 2051<li> 2052<p></p> 2053<div class="dlist"> 2054<dl> 2055<dt class="hdlist1">Requires</dt> 2056<dd> 2057<p><code>Y*</code> should be convertible to <code>T*</code>.</p> 2058</dd> 2059<dt class="hdlist1">Effects</dt> 2060<dd> 2061<p>Constructs a <code>shared_ptr</code>, as if by storing a copy of <code>r.release()</code>.</p> 2062</dd> 2063<dt class="hdlist1">Postconditions</dt> 2064<dd> 2065<p><code>use_count() == 1</code>.</p> 2066</dd> 2067<dt class="hdlist1">Throws</dt> 2068<dd> 2069<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 2070</dd> 2071<dt class="hdlist1">Exception safety</dt> 2072<dd> 2073<p>If an exception is thrown, the constructor has no effect.</p> 2074</dd> 2075</dl> 2076</div> 2077</li> 2078</ul> 2079</div> 2080</div> 2081<div class="sect3"> 2082<h4 id="shared_ptr_unique_ptr_constructor">unique_ptr constructor</h4> 2083<div class="listingblock"> 2084<div class="content"> 2085<pre class="highlight"><code>template<class Y, class D> shared_ptr(std::unique_ptr<Y, D> && r);</code></pre> 2086</div> 2087</div> 2088<div class="ulist none"> 2089<ul class="none"> 2090<li> 2091<p></p> 2092<div class="dlist"> 2093<dl> 2094<dt class="hdlist1">Requires</dt> 2095<dd> 2096<p><code>Y*</code> should be convertible to <code>T*</code>.</p> 2097</dd> 2098<dt class="hdlist1">Effects</dt> 2099<dd> 2100<div class="ulist"> 2101<ul> 2102<li> 2103<p>When <code>r.get() == 0</code>, equivalent to <code>shared_ptr()</code>;</p> 2104</li> 2105<li> 2106<p>When <code>D</code> is not a reference type, equivalent to <code>shared_ptr(r.release(), r.get_deleter())</code>;</p> 2107</li> 2108<li> 2109<p>Otherwise, equivalent to <code>shared_ptr(r.release(), del)</code>, where <code>del</code> is a deleter that stores the reference <code>rd</code> returned 2110from <code>r.get_deleter()</code> and <code>del(p)</code> calls <code>rd(p)</code>.</p> 2111</li> 2112</ul> 2113</div> 2114</dd> 2115<dt class="hdlist1">Throws</dt> 2116<dd> 2117<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 2118</dd> 2119<dt class="hdlist1">Exception safety</dt> 2120<dd> 2121<p>If an exception is thrown, the constructor has no effect.</p> 2122</dd> 2123</dl> 2124</div> 2125</li> 2126</ul> 2127</div> 2128</div> 2129<div class="sect3"> 2130<h4 id="shared_ptr_destructor">destructor</h4> 2131<div class="listingblock"> 2132<div class="content"> 2133<pre class="highlight"><code>~shared_ptr() noexcept;</code></pre> 2134</div> 2135</div> 2136<div class="ulist none"> 2137<ul class="none"> 2138<li> 2139<p></p> 2140<div class="dlist"> 2141<dl> 2142<dt class="hdlist1">Effects</dt> 2143<dd> 2144<div class="ulist"> 2145<ul> 2146<li> 2147<p>If <code>*this</code> is empty, or shares ownership with another <code>shared_ptr</code> instance (<code>use_count() > 1</code>), there are no side effects.</p> 2148</li> 2149<li> 2150<p>Otherwise, if <code>*this</code> owns a pointer <code>p</code> and a deleter <code>d</code>, <code>d(p)</code> is called.</p> 2151</li> 2152<li> 2153<p>Otherwise, <code>*this</code> owns a pointer <code>p</code>, and <code>delete p</code> is called.</p> 2154</li> 2155</ul> 2156</div> 2157</dd> 2158</dl> 2159</div> 2160</li> 2161</ul> 2162</div> 2163</div> 2164<div class="sect3"> 2165<h4 id="shared_ptr_assignment">assignment</h4> 2166<div class="listingblock"> 2167<div class="content"> 2168<pre class="highlight"><code>shared_ptr & operator=(shared_ptr const & r) noexcept;</code></pre> 2169</div> 2170</div> 2171<div class="listingblock"> 2172<div class="content"> 2173<pre class="highlight"><code>template<class Y> shared_ptr & operator=(shared_ptr<Y> const & r) noexcept;</code></pre> 2174</div> 2175</div> 2176<div class="listingblock"> 2177<div class="content"> 2178<pre class="highlight"><code>template<class Y> shared_ptr & operator=(std::auto_ptr<Y> & r);</code></pre> 2179</div> 2180</div> 2181<div class="ulist none"> 2182<ul class="none"> 2183<li> 2184<p></p> 2185<div class="dlist"> 2186<dl> 2187<dt class="hdlist1">Effects</dt> 2188<dd> 2189<p>Equivalent to <code>shared_ptr(r).swap(*this)</code>.</p> 2190</dd> 2191<dt class="hdlist1">Returns</dt> 2192<dd> 2193<p><code>*this</code>.</p> 2194</dd> 2195</dl> 2196</div> 2197</li> 2198</ul> 2199</div> 2200<div class="admonitionblock note"> 2201<table> 2202<tr> 2203<td class="icon"> 2204<div class="title">Note</div> 2205</td> 2206<td class="content"> 2207The use count updates caused by the temporary object construction and destruction are not considered observable side effects, 2208and the implementation is free to meet the effects (and the implied guarantees) via different means, without creating a temporary. 2209</td> 2210</tr> 2211</table> 2212</div> 2213<div class="admonitionblock note"> 2214<table> 2215<tr> 2216<td class="icon"> 2217<div class="title">Note</div> 2218</td> 2219<td class="content"> 2220<div class="paragraph"> 2221<p>In particular, in the example:</p> 2222</div> 2223<div class="listingblock"> 2224<div class="content"> 2225<pre class="highlight"><code>shared_ptr<int> p(new int); 2226shared_ptr<void> q(p); 2227p = p; 2228q = p;</code></pre> 2229</div> 2230</div> 2231<div class="paragraph"> 2232<p>both assignments may be no-ops.</p> 2233</div> 2234</td> 2235</tr> 2236</table> 2237</div> 2238<div class="listingblock"> 2239<div class="content"> 2240<pre class="highlight"><code>shared_ptr & operator=(shared_ptr && r) noexcept;</code></pre> 2241</div> 2242</div> 2243<div class="listingblock"> 2244<div class="content"> 2245<pre class="highlight"><code>template<class Y> shared_ptr & operator=(shared_ptr<Y> && r) noexcept;</code></pre> 2246</div> 2247</div> 2248<div class="listingblock"> 2249<div class="content"> 2250<pre class="highlight"><code>template<class Y> shared_ptr & operator=(std::auto_ptr<Y> && r);</code></pre> 2251</div> 2252</div> 2253<div class="listingblock"> 2254<div class="content"> 2255<pre class="highlight"><code>template<class Y, class D> shared_ptr & operator=(std::unique_ptr<Y, D> && r);</code></pre> 2256</div> 2257</div> 2258<div class="ulist none"> 2259<ul class="none"> 2260<li> 2261<p></p> 2262<div class="dlist"> 2263<dl> 2264<dt class="hdlist1">Effects</dt> 2265<dd> 2266<p>Equivalent to <code>shared_ptr(std::move(r)).swap(*this)</code>.</p> 2267</dd> 2268<dt class="hdlist1">Returns</dt> 2269<dd> 2270<p><code>*this</code>.</p> 2271</dd> 2272</dl> 2273</div> 2274</li> 2275</ul> 2276</div> 2277<div class="listingblock"> 2278<div class="content"> 2279<pre class="highlight"><code>shared_ptr & operator=(std::nullptr_t) noexcept;</code></pre> 2280</div> 2281</div> 2282<div class="ulist none"> 2283<ul class="none"> 2284<li> 2285<p></p> 2286<div class="dlist"> 2287<dl> 2288<dt class="hdlist1">Effects</dt> 2289<dd> 2290<p>Equivalent to <code>shared_ptr().swap(*this)</code>.</p> 2291</dd> 2292<dt class="hdlist1">Returns</dt> 2293<dd> 2294<p><code>*this</code>.</p> 2295</dd> 2296</dl> 2297</div> 2298</li> 2299</ul> 2300</div> 2301</div> 2302<div class="sect3"> 2303<h4 id="shared_ptr_reset">reset</h4> 2304<div class="listingblock"> 2305<div class="content"> 2306<pre class="highlight"><code>void reset() noexcept;</code></pre> 2307</div> 2308</div> 2309<div class="ulist none"> 2310<ul class="none"> 2311<li> 2312<p></p> 2313<div class="dlist"> 2314<dl> 2315<dt class="hdlist1">Effects</dt> 2316<dd> 2317<p>Equivalent to <code>shared_ptr().swap(*this)</code>.</p> 2318</dd> 2319</dl> 2320</div> 2321</li> 2322</ul> 2323</div> 2324<div class="listingblock"> 2325<div class="content"> 2326<pre class="highlight"><code>template<class Y> void reset(Y * p);</code></pre> 2327</div> 2328</div> 2329<div class="ulist none"> 2330<ul class="none"> 2331<li> 2332<p></p> 2333<div class="dlist"> 2334<dl> 2335<dt class="hdlist1">Effects</dt> 2336<dd> 2337<p>Equivalent to <code>shared_ptr(p).swap(*this)</code>.</p> 2338</dd> 2339</dl> 2340</div> 2341</li> 2342</ul> 2343</div> 2344<div class="listingblock"> 2345<div class="content"> 2346<pre class="highlight"><code>template<class Y, class D> void reset(Y * p, D d);</code></pre> 2347</div> 2348</div> 2349<div class="ulist none"> 2350<ul class="none"> 2351<li> 2352<p></p> 2353<div class="dlist"> 2354<dl> 2355<dt class="hdlist1">Effects</dt> 2356<dd> 2357<p>Equivalent to <code>shared_ptr(p, d).swap(*this)</code>.</p> 2358</dd> 2359</dl> 2360</div> 2361</li> 2362</ul> 2363</div> 2364<div class="listingblock"> 2365<div class="content"> 2366<pre class="highlight"><code>template<class Y, class D, class A> void reset(Y * p, D d, A a);</code></pre> 2367</div> 2368</div> 2369<div class="ulist none"> 2370<ul class="none"> 2371<li> 2372<p></p> 2373<div class="dlist"> 2374<dl> 2375<dt class="hdlist1">Effects</dt> 2376<dd> 2377<p>Equivalent to <code>shared_ptr(p, d, a).swap(*this)</code>.</p> 2378</dd> 2379</dl> 2380</div> 2381</li> 2382</ul> 2383</div> 2384<div class="listingblock"> 2385<div class="content"> 2386<pre class="highlight"><code>template<class Y> void reset(shared_ptr<Y> const & r, element_type * p) noexcept;</code></pre> 2387</div> 2388</div> 2389<div class="ulist none"> 2390<ul class="none"> 2391<li> 2392<p></p> 2393<div class="dlist"> 2394<dl> 2395<dt class="hdlist1">Effects</dt> 2396<dd> 2397<p>Equivalent to <code>shared_ptr(r, p).swap(*this)</code>.</p> 2398</dd> 2399</dl> 2400</div> 2401</li> 2402</ul> 2403</div> 2404<div class="listingblock"> 2405<div class="content"> 2406<pre class="highlight"><code>template<class Y> void reset(shared_ptr<Y> && r, element_type * p) noexcept;</code></pre> 2407</div> 2408</div> 2409<div class="ulist none"> 2410<ul class="none"> 2411<li> 2412<p></p> 2413<div class="dlist"> 2414<dl> 2415<dt class="hdlist1">Effects</dt> 2416<dd> 2417<p>Equivalent to <code>shared_ptr(std::move(r), p).swap(*this)</code>.</p> 2418</dd> 2419</dl> 2420</div> 2421</li> 2422</ul> 2423</div> 2424</div> 2425<div class="sect3"> 2426<h4 id="shared_ptr_indirection">indirection</h4> 2427<div class="listingblock"> 2428<div class="content"> 2429<pre class="highlight"><code>T & operator*() const noexcept;</code></pre> 2430</div> 2431</div> 2432<div class="ulist none"> 2433<ul class="none"> 2434<li> 2435<p></p> 2436<div class="dlist"> 2437<dl> 2438<dt class="hdlist1">Requires</dt> 2439<dd> 2440<p><code>T</code> should not be an array type. The stored pointer must not be 0.</p> 2441</dd> 2442<dt class="hdlist1">Returns</dt> 2443<dd> 2444<p><code>*get()</code>.</p> 2445</dd> 2446</dl> 2447</div> 2448</li> 2449</ul> 2450</div> 2451<div class="listingblock"> 2452<div class="content"> 2453<pre class="highlight"><code>T * operator->() const noexcept;</code></pre> 2454</div> 2455</div> 2456<div class="ulist none"> 2457<ul class="none"> 2458<li> 2459<p></p> 2460<div class="dlist"> 2461<dl> 2462<dt class="hdlist1">Requires</dt> 2463<dd> 2464<p><code>T</code> should not be an array type. The stored pointer must not be 0.</p> 2465</dd> 2466<dt class="hdlist1">Returns</dt> 2467<dd> 2468<p><code>get()</code>.</p> 2469</dd> 2470</dl> 2471</div> 2472</li> 2473</ul> 2474</div> 2475<div class="listingblock"> 2476<div class="content"> 2477<pre class="highlight"><code>element_type & operator[](std::ptrdiff_t i) const noexcept;</code></pre> 2478</div> 2479</div> 2480<div class="ulist none"> 2481<ul class="none"> 2482<li> 2483<p></p> 2484<div class="dlist"> 2485<dl> 2486<dt class="hdlist1">Requires</dt> 2487<dd> 2488<p><code>T</code> should be an array type. The stored pointer must not be 0. <code>i >= 0</code>. If <code>T</code> is <code>U[N]</code>, <code>i < N</code>.</p> 2489</dd> 2490<dt class="hdlist1">Returns</dt> 2491<dd> 2492<p><code>get()[i]</code>.</p> 2493</dd> 2494</dl> 2495</div> 2496</li> 2497</ul> 2498</div> 2499</div> 2500<div class="sect3"> 2501<h4 id="shared_ptr_get">get</h4> 2502<div class="listingblock"> 2503<div class="content"> 2504<pre class="highlight"><code>element_type * get() const noexcept;</code></pre> 2505</div> 2506</div> 2507<div class="ulist none"> 2508<ul class="none"> 2509<li> 2510<p></p> 2511<div class="dlist"> 2512<dl> 2513<dt class="hdlist1">Returns</dt> 2514<dd> 2515<p>The stored pointer.</p> 2516</dd> 2517</dl> 2518</div> 2519</li> 2520</ul> 2521</div> 2522</div> 2523<div class="sect3"> 2524<h4 id="shared_ptr_unique">unique</h4> 2525<div class="listingblock"> 2526<div class="content"> 2527<pre class="highlight"><code>bool unique() const noexcept;</code></pre> 2528</div> 2529</div> 2530<div class="ulist none"> 2531<ul class="none"> 2532<li> 2533<p></p> 2534<div class="dlist"> 2535<dl> 2536<dt class="hdlist1">Returns</dt> 2537<dd> 2538<p><code>use_count() == 1</code>.</p> 2539</dd> 2540</dl> 2541</div> 2542</li> 2543</ul> 2544</div> 2545</div> 2546<div class="sect3"> 2547<h4 id="shared_ptr_use_count">use_count</h4> 2548<div class="listingblock"> 2549<div class="content"> 2550<pre class="highlight"><code>long use_count() const noexcept;</code></pre> 2551</div> 2552</div> 2553<div class="ulist none"> 2554<ul class="none"> 2555<li> 2556<p></p> 2557<div class="dlist"> 2558<dl> 2559<dt class="hdlist1">Returns</dt> 2560<dd> 2561<p>The number of <code>shared_ptr</code> objects, <code>*this</code> included, that share ownership with <code>*this</code>, or 0 when <code>*this</code> is empty.</p> 2562</dd> 2563</dl> 2564</div> 2565</li> 2566</ul> 2567</div> 2568</div> 2569<div class="sect3"> 2570<h4 id="shared_ptr_conversions">conversions</h4> 2571<div class="listingblock"> 2572<div class="content"> 2573<pre class="highlight"><code>explicit operator bool() const noexcept;</code></pre> 2574</div> 2575</div> 2576<div class="ulist none"> 2577<ul class="none"> 2578<li> 2579<p></p> 2580<div class="dlist"> 2581<dl> 2582<dt class="hdlist1">Returns</dt> 2583<dd> 2584<p><code>get() != 0</code>.</p> 2585</dd> 2586</dl> 2587</div> 2588</li> 2589</ul> 2590</div> 2591<div class="admonitionblock note"> 2592<table> 2593<tr> 2594<td class="icon"> 2595<div class="title">Note</div> 2596</td> 2597<td class="content"> 2598This conversion operator allows <code>shared_ptr</code> objects to be used in boolean contexts, like <code>if(p && p->valid()) {}</code>. 2599</td> 2600</tr> 2601</table> 2602</div> 2603<div class="admonitionblock note"> 2604<table> 2605<tr> 2606<td class="icon"> 2607<div class="title">Note</div> 2608</td> 2609<td class="content"> 2610The conversion to <code>bool</code> is not merely syntactic sugar. It allows <code>shared_ptr</code> variables to be declared in conditions when using 2611<code>dynamic_pointer_cast</code> or <code>weak_ptr::lock</code>. 2612</td> 2613</tr> 2614</table> 2615</div> 2616<div class="admonitionblock note"> 2617<table> 2618<tr> 2619<td class="icon"> 2620<div class="title">Note</div> 2621</td> 2622<td class="content"> 2623On C++03 compilers, the return value is of an unspecified type. 2624</td> 2625</tr> 2626</table> 2627</div> 2628</div> 2629<div class="sect3"> 2630<h4 id="shared_ptr_swap">swap</h4> 2631<div class="listingblock"> 2632<div class="content"> 2633<pre class="highlight"><code>void swap(shared_ptr & b) noexcept;</code></pre> 2634</div> 2635</div> 2636<div class="ulist none"> 2637<ul class="none"> 2638<li> 2639<p></p> 2640<div class="dlist"> 2641<dl> 2642<dt class="hdlist1">Effects</dt> 2643<dd> 2644<p>Exchanges the contents of the two smart pointers.</p> 2645</dd> 2646</dl> 2647</div> 2648</li> 2649</ul> 2650</div> 2651</div> 2652<div class="sect3"> 2653<h4 id="shared_ptr_owner_before">owner_before</h4> 2654<div class="listingblock"> 2655<div class="content"> 2656<pre class="highlight"><code>template<class Y> bool owner_before(shared_ptr<Y> const & r) const noexcept;</code></pre> 2657</div> 2658</div> 2659<div class="listingblock"> 2660<div class="content"> 2661<pre class="highlight"><code>template<class Y> bool owner_before(weak_ptr<Y> const & r) const noexcept;</code></pre> 2662</div> 2663</div> 2664<div class="ulist none"> 2665<ul class="none"> 2666<li> 2667<p></p> 2668<div class="dlist"> 2669<dl> 2670<dt class="hdlist1">Returns</dt> 2671<dd> 2672<p>See the description of <code>operator<</code>.</p> 2673</dd> 2674</dl> 2675</div> 2676</li> 2677</ul> 2678</div> 2679</div> 2680<div class="sect3"> 2681<h4 id="shared_ptr_owner_equals">owner_equals</h4> 2682<div class="listingblock"> 2683<div class="content"> 2684<pre class="highlight"><code>template<class Y> bool owner_equals(shared_ptr<Y> const & r) const noexcept;</code></pre> 2685</div> 2686</div> 2687<div class="listingblock"> 2688<div class="content"> 2689<pre class="highlight"><code>template<class Y> bool owner_equals(weak_ptr<Y> const & r) const noexcept;</code></pre> 2690</div> 2691</div> 2692<div class="ulist none"> 2693<ul class="none"> 2694<li> 2695<p></p> 2696<div class="dlist"> 2697<dl> 2698<dt class="hdlist1">Returns</dt> 2699<dd> 2700<p><code>true</code> if and only if <code>*this</code> and <code>r</code> share ownership or are both empty.</p> 2701</dd> 2702</dl> 2703</div> 2704</li> 2705</ul> 2706</div> 2707</div> 2708<div class="sect3"> 2709<h4 id="shared_ptr_owner_hash_value">owner_hash_value</h4> 2710<div class="listingblock"> 2711<div class="content"> 2712<pre class="highlight"><code>std::size_t owner_hash_value() const noexcept;</code></pre> 2713</div> 2714</div> 2715<div class="ulist none"> 2716<ul class="none"> 2717<li> 2718<p></p> 2719<div class="dlist"> 2720<dl> 2721<dt class="hdlist1">Returns</dt> 2722<dd> 2723<p>An unspecified hash value such that two instances that share ownership 2724have the same hash value.</p> 2725</dd> 2726</dl> 2727</div> 2728</li> 2729</ul> 2730</div> 2731</div> 2732</div> 2733<div class="sect2"> 2734<h3 id="shared_ptr_free_functions">Free Functions</h3> 2735<div class="sect3"> 2736<h4 id="shared_ptr_comparison">comparison</h4> 2737<div class="listingblock"> 2738<div class="content"> 2739<pre class="highlight"><code>template<class T, class U> 2740 bool operator==(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept;</code></pre> 2741</div> 2742</div> 2743<div class="ulist none"> 2744<ul class="none"> 2745<li> 2746<p></p> 2747<div class="dlist"> 2748<dl> 2749<dt class="hdlist1">Returns</dt> 2750<dd> 2751<p><code>a.get() == b.get()</code>.</p> 2752</dd> 2753</dl> 2754</div> 2755</li> 2756</ul> 2757</div> 2758<div class="listingblock"> 2759<div class="content"> 2760<pre class="highlight"><code>template<class T, class U> 2761 bool operator!=(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept;</code></pre> 2762</div> 2763</div> 2764<div class="ulist none"> 2765<ul class="none"> 2766<li> 2767<p></p> 2768<div class="dlist"> 2769<dl> 2770<dt class="hdlist1">Returns</dt> 2771<dd> 2772<p><code>a.get() != b.get()</code>.</p> 2773</dd> 2774</dl> 2775</div> 2776</li> 2777</ul> 2778</div> 2779<div class="listingblock"> 2780<div class="content"> 2781<pre class="highlight"><code>template<class T> bool operator==(shared_ptr<T> const & p, std::nullptr_t) noexcept;</code></pre> 2782</div> 2783</div> 2784<div class="listingblock"> 2785<div class="content"> 2786<pre class="highlight"><code>template<class T> bool operator==(std::nullptr_t, shared_ptr<T> const & p) noexcept;</code></pre> 2787</div> 2788</div> 2789<div class="ulist none"> 2790<ul class="none"> 2791<li> 2792<p></p> 2793<div class="dlist"> 2794<dl> 2795<dt class="hdlist1">Returns</dt> 2796<dd> 2797<p><code>p.get() == 0</code>.</p> 2798</dd> 2799</dl> 2800</div> 2801</li> 2802</ul> 2803</div> 2804<div class="listingblock"> 2805<div class="content"> 2806<pre class="highlight"><code>template<class T> bool operator!=(shared_ptr<T> const & p, std::nullptr_t) noexcept;</code></pre> 2807</div> 2808</div> 2809<div class="listingblock"> 2810<div class="content"> 2811<pre class="highlight"><code>template<class T> bool operator!=(std::nullptr_t, shared_ptr<T> const & p) noexcept;</code></pre> 2812</div> 2813</div> 2814<div class="ulist none"> 2815<ul class="none"> 2816<li> 2817<p></p> 2818<div class="dlist"> 2819<dl> 2820<dt class="hdlist1">Returns</dt> 2821<dd> 2822<p><code>p.get() != 0</code>.</p> 2823</dd> 2824</dl> 2825</div> 2826</li> 2827</ul> 2828</div> 2829<div class="listingblock"> 2830<div class="content"> 2831<pre class="highlight"><code>template<class T, class U> 2832 bool operator<(shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept;</code></pre> 2833</div> 2834</div> 2835<div class="ulist none"> 2836<ul class="none"> 2837<li> 2838<p></p> 2839<div class="dlist"> 2840<dl> 2841<dt class="hdlist1">Returns</dt> 2842<dd> 2843<p>An unspecified value such that</p> 2844<div class="ulist"> 2845<ul> 2846<li> 2847<p><code>operator<</code> is a strict weak ordering as described in section [lib.alg.sorting] of the C++ standard;</p> 2848</li> 2849<li> 2850<p>under the equivalence relation defined by <code>operator<</code>, <code>!(a < b) && !(b < a)</code>, two <code>shared_ptr</code> instances 2851are equivalent if and only if they share ownership or are both empty.</p> 2852</li> 2853</ul> 2854</div> 2855</dd> 2856</dl> 2857</div> 2858</li> 2859</ul> 2860</div> 2861<div class="admonitionblock note"> 2862<table> 2863<tr> 2864<td class="icon"> 2865<div class="title">Note</div> 2866</td> 2867<td class="content"> 2868Allows <code>shared_ptr</code> objects to be used as keys in associative containers. 2869</td> 2870</tr> 2871</table> 2872</div> 2873<div class="admonitionblock note"> 2874<table> 2875<tr> 2876<td class="icon"> 2877<div class="title">Note</div> 2878</td> 2879<td class="content"> 2880The rest of the comparison operators are omitted by design. 2881</td> 2882</tr> 2883</table> 2884</div> 2885</div> 2886<div class="sect3"> 2887<h4 id="shared_ptr_swap_2">swap</h4> 2888<div class="listingblock"> 2889<div class="content"> 2890<pre class="highlight"><code>template<class T> void swap(shared_ptr<T> & a, shared_ptr<T> & b) noexcept;</code></pre> 2891</div> 2892</div> 2893<div class="ulist none"> 2894<ul class="none"> 2895<li> 2896<p></p> 2897<div class="dlist"> 2898<dl> 2899<dt class="hdlist1">Effects</dt> 2900<dd> 2901<p>Equivalent to <code>a.swap(b)</code>.</p> 2902</dd> 2903</dl> 2904</div> 2905</li> 2906</ul> 2907</div> 2908</div> 2909<div class="sect3"> 2910<h4 id="shared_ptr_get_pointer">get_pointer</h4> 2911<div class="listingblock"> 2912<div class="content"> 2913<pre class="highlight"><code>template<class T> 2914 typename shared_ptr<T>::element_type * 2915 get_pointer(shared_ptr<T> const & p) noexcept;</code></pre> 2916</div> 2917</div> 2918<div class="ulist none"> 2919<ul class="none"> 2920<li> 2921<p></p> 2922<div class="dlist"> 2923<dl> 2924<dt class="hdlist1">Returns</dt> 2925<dd> 2926<p><code>p.get()</code>.</p> 2927</dd> 2928</dl> 2929</div> 2930</li> 2931</ul> 2932</div> 2933<div class="admonitionblock note"> 2934<table> 2935<tr> 2936<td class="icon"> 2937<div class="title">Note</div> 2938</td> 2939<td class="content"> 2940Provided as an aid to generic programming. Used by <code>mem_fn</code>. 2941</td> 2942</tr> 2943</table> 2944</div> 2945</div> 2946<div class="sect3"> 2947<h4 id="shared_ptr_static_pointer_cast">static_pointer_cast</h4> 2948<div class="listingblock"> 2949<div class="content"> 2950<pre class="highlight"><code>template<class T, class U> 2951 shared_ptr<T> static_pointer_cast(shared_ptr<U> const & r) noexcept;</code></pre> 2952</div> 2953</div> 2954<div class="ulist none"> 2955<ul class="none"> 2956<li> 2957<p></p> 2958<div class="dlist"> 2959<dl> 2960<dt class="hdlist1">Requires</dt> 2961<dd> 2962<p>The expression <code>static_cast<T*>( (U*)0 )</code> must be well-formed.</p> 2963</dd> 2964<dt class="hdlist1">Returns</dt> 2965<dd> 2966<p><code>shared_ptr<T>( r, static_cast<typename shared_ptr<T>::element_type*>(r.get()) )</code>.</p> 2967</dd> 2968</dl> 2969</div> 2970</li> 2971</ul> 2972</div> 2973<div class="admonitionblock caution"> 2974<table> 2975<tr> 2976<td class="icon"> 2977<div class="title">Caution</div> 2978</td> 2979<td class="content"> 2980The seemingly equivalent expression <code>shared_ptr<T>(static_cast<T*>(r.get()))</code> will eventually 2981result in undefined behavior, attempting to delete the same object twice. 2982</td> 2983</tr> 2984</table> 2985</div> 2986</div> 2987<div class="sect3"> 2988<h4 id="shared_ptr_const_pointer_cast">const_pointer_cast</h4> 2989<div class="listingblock"> 2990<div class="content"> 2991<pre class="highlight"><code>template<class T, class U> 2992 shared_ptr<T> const_pointer_cast(shared_ptr<U> const & r) noexcept;</code></pre> 2993</div> 2994</div> 2995<div class="ulist none"> 2996<ul class="none"> 2997<li> 2998<p></p> 2999<div class="dlist"> 3000<dl> 3001<dt class="hdlist1">Requires</dt> 3002<dd> 3003<p>The expression <code>const_cast<T*>( (U*)0 )</code> must be well-formed.</p> 3004</dd> 3005<dt class="hdlist1">Returns</dt> 3006<dd> 3007<p><code>shared_ptr<T>( r, const_cast<typename shared_ptr<T>::element_type*>(r.get()) )</code>.</p> 3008</dd> 3009</dl> 3010</div> 3011</li> 3012</ul> 3013</div> 3014</div> 3015<div class="sect3"> 3016<h4 id="shared_ptr_dynamic_pointer_cast">dynamic_pointer_cast</h4> 3017<div class="listingblock"> 3018<div class="content"> 3019<pre class="highlight"><code>template<class T, class U> 3020 shared_ptr<T> dynamic_pointer_cast(shared_ptr<U> const & r) noexcept;</code></pre> 3021</div> 3022</div> 3023<div class="ulist none"> 3024<ul class="none"> 3025<li> 3026<p></p> 3027<div class="dlist"> 3028<dl> 3029<dt class="hdlist1">Requires</dt> 3030<dd> 3031<p>The expression <code>dynamic_cast<T*>( (U*)0 )</code> must be well-formed.</p> 3032</dd> 3033<dt class="hdlist1">Returns</dt> 3034<dd> 3035<div class="ulist"> 3036<ul> 3037<li> 3038<p>When <code>dynamic_cast<typename shared_ptr<T>::element_type*>(r.get())</code> returns a nonzero value <code>p</code>, <code>shared_ptr<T>(r, p)</code>;</p> 3039</li> 3040<li> 3041<p>Otherwise, <code>shared_ptr<T>()</code>.</p> 3042</li> 3043</ul> 3044</div> 3045</dd> 3046</dl> 3047</div> 3048</li> 3049</ul> 3050</div> 3051</div> 3052<div class="sect3"> 3053<h4 id="shared_ptr_reinterpret_pointer_cast">reinterpret_pointer_cast</h4> 3054<div class="listingblock"> 3055<div class="content"> 3056<pre class="highlight"><code>template<class T, class U> 3057 shared_ptr<T> reinterpret_pointer_cast(shared_ptr<U> const & r) noexcept;</code></pre> 3058</div> 3059</div> 3060<div class="ulist none"> 3061<ul class="none"> 3062<li> 3063<p></p> 3064<div class="dlist"> 3065<dl> 3066<dt class="hdlist1">Requires</dt> 3067<dd> 3068<p>The expression <code>reinterpret_cast<T*>( (U*)0 )</code> must be well-formed.</p> 3069</dd> 3070<dt class="hdlist1">Returns</dt> 3071<dd> 3072<p><code>shared_ptr<T>( r, reinterpret_cast<typename shared_ptr<T>::element_type*>(r.get()) )</code>.</p> 3073</dd> 3074</dl> 3075</div> 3076</li> 3077</ul> 3078</div> 3079</div> 3080<div class="sect3"> 3081<h4 id="shared_ptr_operator">operator<<</h4> 3082<div class="listingblock"> 3083<div class="content"> 3084<pre class="highlight"><code>template<class E, class T, class Y> 3085 std::basic_ostream<E, T> & 3086 operator<< (std::basic_ostream<E, T> & os, shared_ptr<Y> const & p);</code></pre> 3087</div> 3088</div> 3089<div class="ulist none"> 3090<ul class="none"> 3091<li> 3092<p></p> 3093<div class="dlist"> 3094<dl> 3095<dt class="hdlist1">Effects</dt> 3096<dd> 3097<p><code>os << p.get();</code>.</p> 3098</dd> 3099<dt class="hdlist1">Returns</dt> 3100<dd> 3101<p><code>os</code>.</p> 3102</dd> 3103</dl> 3104</div> 3105</li> 3106</ul> 3107</div> 3108</div> 3109<div class="sect3"> 3110<h4 id="shared_ptr_get_deleter">get_deleter</h4> 3111<div class="listingblock"> 3112<div class="content"> 3113<pre class="highlight"><code>template<class D, class T> 3114 D * get_deleter(shared_ptr<T> const & p) noexcept;</code></pre> 3115</div> 3116</div> 3117<div class="ulist none"> 3118<ul class="none"> 3119<li> 3120<p></p> 3121<div class="dlist"> 3122<dl> 3123<dt class="hdlist1">Returns</dt> 3124<dd> 3125<p>If <code>*this</code> owns a deleter <code>d</code> of type (cv-unqualified) <code>D</code>, returns <code>&d</code>; otherwise returns 0.</p> 3126</dd> 3127</dl> 3128</div> 3129</li> 3130</ul> 3131</div> 3132</div> 3133<div class="sect3"> 3134<h4 id="shared_ptr_atomic_access">Atomic Access</h4> 3135<div class="admonitionblock note"> 3136<table> 3137<tr> 3138<td class="icon"> 3139<div class="title">Note</div> 3140</td> 3141<td class="content"> 3142The function in this section are atomic with respect to the first <code>shared_ptr</code> argument, 3143 identified by <code>*p</code>. Concurrent access to the same <code>shared_ptr</code> instance is not a data race, if 3144 done exclusively by the functions in this section. 3145</td> 3146</tr> 3147</table> 3148</div> 3149<div class="listingblock"> 3150<div class="content"> 3151<pre class="highlight"><code>template<class T> bool atomic_is_lock_free( shared_ptr<T> const * p ) noexcept;</code></pre> 3152</div> 3153</div> 3154<div class="ulist none"> 3155<ul class="none"> 3156<li> 3157<p></p> 3158<div class="dlist"> 3159<dl> 3160<dt class="hdlist1">Returns</dt> 3161<dd> 3162<p><code>false</code>.</p> 3163</dd> 3164</dl> 3165</div> 3166</li> 3167</ul> 3168</div> 3169<div class="admonitionblock note"> 3170<table> 3171<tr> 3172<td class="icon"> 3173<div class="title">Note</div> 3174</td> 3175<td class="content"> 3176This implementation is not lock-free. 3177</td> 3178</tr> 3179</table> 3180</div> 3181<div class="listingblock"> 3182<div class="content"> 3183<pre class="highlight"><code>template<class T> shared_ptr<T> atomic_load( shared_ptr<T> const * p ) noexcept;</code></pre> 3184</div> 3185</div> 3186<div class="listingblock"> 3187<div class="content"> 3188<pre class="highlight"><code>template<class T> shared_ptr<T> atomic_load_explicit( shared_ptr<T> const * p, int ) noexcept;</code></pre> 3189</div> 3190</div> 3191<div class="ulist none"> 3192<ul class="none"> 3193<li> 3194<p></p> 3195<div class="dlist"> 3196<dl> 3197<dt class="hdlist1">Returns</dt> 3198<dd> 3199<p><code>*p</code>.</p> 3200</dd> 3201</dl> 3202</div> 3203</li> 3204</ul> 3205</div> 3206<div class="admonitionblock note"> 3207<table> 3208<tr> 3209<td class="icon"> 3210<div class="title">Note</div> 3211</td> 3212<td class="content"> 3213The <code>int</code> argument is the <code>memory_order</code>, but this implementation does not use it, as it’s lock-based 3214 and therefore always sequentially consistent. 3215</td> 3216</tr> 3217</table> 3218</div> 3219<div class="listingblock"> 3220<div class="content"> 3221<pre class="highlight"><code>template<class T> 3222 void atomic_store( shared_ptr<T> * p, shared_ptr<T> r ) noexcept;</code></pre> 3223</div> 3224</div> 3225<div class="listingblock"> 3226<div class="content"> 3227<pre class="highlight"><code>template<class T> 3228 void atomic_store_explicit( shared_ptr<T> * p, shared_ptr<T> r, int ) noexcept;</code></pre> 3229</div> 3230</div> 3231<div class="ulist none"> 3232<ul class="none"> 3233<li> 3234<p></p> 3235<div class="dlist"> 3236<dl> 3237<dt class="hdlist1">Effects</dt> 3238<dd> 3239<p><code>p->swap(r)</code>.</p> 3240</dd> 3241</dl> 3242</div> 3243</li> 3244</ul> 3245</div> 3246<div class="listingblock"> 3247<div class="content"> 3248<pre class="highlight"><code>template<class T> 3249 shared_ptr<T> atomic_exchange( shared_ptr<T> * p, shared_ptr<T> r ) noexcept;</code></pre> 3250</div> 3251</div> 3252<div class="listingblock"> 3253<div class="content"> 3254<pre class="highlight"><code>template<class T> 3255 shared_ptr<T> atomic_exchange_explicit( 3256 shared_ptr<T> * p, shared_ptr<T> r, int ) noexcept;</code></pre> 3257</div> 3258</div> 3259<div class="ulist none"> 3260<ul class="none"> 3261<li> 3262<p></p> 3263<div class="dlist"> 3264<dl> 3265<dt class="hdlist1">Effects</dt> 3266<dd> 3267<p><code>p->swap(r)</code>.</p> 3268</dd> 3269<dt class="hdlist1">Returns</dt> 3270<dd> 3271<p>The old value of <code>*p</code>.</p> 3272</dd> 3273</dl> 3274</div> 3275</li> 3276</ul> 3277</div> 3278<div class="listingblock"> 3279<div class="content"> 3280<pre class="highlight"><code>template<class T> 3281 bool atomic_compare_exchange( 3282 shared_ptr<T> * p, shared_ptr<T> * v, shared_ptr<T> w ) noexcept;</code></pre> 3283</div> 3284</div> 3285<div class="listingblock"> 3286<div class="content"> 3287<pre class="highlight"><code>template<class T> 3288 bool atomic_compare_exchange_explicit( 3289 shared_ptr<T> * p, shared_ptr<T> * v, shared_ptr<T> w, int, int ) noexcept;</code></pre> 3290</div> 3291</div> 3292<div class="ulist none"> 3293<ul class="none"> 3294<li> 3295<p></p> 3296<div class="dlist"> 3297<dl> 3298<dt class="hdlist1">Effects</dt> 3299<dd> 3300<p>If <code>*p</code> is equivalent to <code>*v</code>, assigns <code>w</code> to <code>*p</code>, otherwise assigns <code>*p</code> to <code>*v</code>.</p> 3301</dd> 3302<dt class="hdlist1">Returns</dt> 3303<dd> 3304<p><code>true</code> if <code>*p</code> was equivalent to <code>*v</code>, <code>false</code> otherwise.</p> 3305</dd> 3306<dt class="hdlist1">Remarks</dt> 3307<dd> 3308<p>Two <code>shared_ptr</code> instances are equivalent if they store the same pointer value and <em>share ownership</em>.</p> 3309</dd> 3310</dl> 3311</div> 3312</li> 3313</ul> 3314</div> 3315</div> 3316</div> 3317<div class="sect2"> 3318<h3 id="shared_ptr_example">Example</h3> 3319<div class="paragraph"> 3320<p>See <a href="../../example/shared_ptr_example.cpp">shared_ptr_example.cpp</a> for a complete example program. The program builds a 3321<code>std::vector</code> and <code>std::set</code> of <code>shared_ptr</code> objects.</p> 3322</div> 3323<div class="paragraph"> 3324<p>Note that after the containers have been populated, some of the <code>shared_ptr</code> objects will have a use count of 1 rather than 3325a use count of 2, since the set is a <code>std::set</code> rather than a <code>std::multiset</code>, and thus does not contain duplicate entries. 3326Furthermore, the use count may be even higher at various times while <code>push_back</code> and <code>insert</code> container operations are performed. 3327More complicated yet, the container operations may throw exceptions under a variety of circumstances. Getting the memory management 3328and exception handling in this example right without a smart pointer would be a nightmare.</p> 3329</div> 3330</div> 3331<div class="sect2"> 3332<h3 id="shared_ptr_handlebody_idiom">Handle/Body Idiom</h3> 3333<div class="paragraph"> 3334<p>One common usage of <code>shared_ptr</code> is to implement a handle/body (also called pimpl) idiom which avoids exposing the body (implementation) 3335in the header file.</p> 3336</div> 3337<div class="paragraph"> 3338<p>The <a href="../../example/shared_ptr_example2_test.cpp">shared_ptr_example2_test.cpp</a> sample program includes a header file, 3339<a href="../../example/shared_ptr_example2.hpp">shared_ptr_example2.hpp</a>, which uses a <code>shared_ptr</code> to an incomplete type to hide the implementation. 3340The instantiation of member functions which require a complete type occurs in the <a href="../../example/shared_ptr_example2.cpp">shared_ptr_example2.cpp</a> 3341implementation file. Note that there is no need for an explicit destructor. Unlike <code>~scoped_ptr</code>, <code>~shared_ptr</code> does not require that <code>T</code> be a complete type.</p> 3342</div> 3343</div> 3344<div class="sect2"> 3345<h3 id="shared_ptr_thread_safety">Thread Safety</h3> 3346<div class="paragraph"> 3347<p><code>shared_ptr</code> objects offer the same level of thread safety as built-in types. A <code>shared_ptr</code> instance can be "read" (accessed using only const operations) 3348simultaneously by multiple threads. Different <code>shared_ptr</code> instances can be "written to" (accessed using mutable operations such as <code>operator=</code> or <code>reset</code>) 3349simultaneously by multiple threads (even when these instances are copies, and share the same reference count underneath.)</p> 3350</div> 3351<div class="paragraph"> 3352<p>Any other simultaneous accesses result in undefined behavior.</p> 3353</div> 3354<div class="paragraph"> 3355<p>Examples:</p> 3356</div> 3357<div class="listingblock"> 3358<div class="content"> 3359<pre class="highlight"><code>shared_ptr<int> p(new int(42));</code></pre> 3360</div> 3361</div> 3362<div class="listingblock"> 3363<div class="title">Code Example 4. Reading a <code>shared_ptr</code> from two threads</div> 3364<div class="content"> 3365<pre class="highlight"><code>// thread A 3366shared_ptr<int> p2(p); // reads p 3367 3368// thread B 3369shared_ptr<int> p3(p); // OK, multiple reads are safe</code></pre> 3370</div> 3371</div> 3372<div class="listingblock"> 3373<div class="title">Code Example 5. Writing different <code>shared_ptr</code> instances from two threads</div> 3374<div class="content"> 3375<pre class="highlight"><code>// thread A 3376p.reset(new int(1912)); // writes p 3377 3378// thread B 3379p2.reset(); // OK, writes p2</code></pre> 3380</div> 3381</div> 3382<div class="listingblock"> 3383<div class="title">Code Example 6. Reading and writing a <code>shared_ptr</code> from two threads</div> 3384<div class="content"> 3385<pre class="highlight"><code>// thread A 3386p = p3; // reads p3, writes p 3387 3388// thread B 3389p3.reset(); // writes p3; undefined, simultaneous read/write</code></pre> 3390</div> 3391</div> 3392<div class="listingblock"> 3393<div class="title">Code Example 7. Reading and destroying a <code>shared_ptr</code> from two threads</div> 3394<div class="content"> 3395<pre class="highlight"><code>// thread A 3396p3 = p2; // reads p2, writes p3 3397 3398// thread B 3399// p2 goes out of scope: undefined, the destructor is considered a "write access"</code></pre> 3400</div> 3401</div> 3402<div class="listingblock"> 3403<div class="title">Code Example 8. Writing a <code>shared_ptr</code> from two threads</div> 3404<div class="content"> 3405<pre class="highlight"><code>// thread A 3406p3.reset(new int(1)); 3407 3408// thread B 3409p3.reset(new int(2)); // undefined, multiple writes</code></pre> 3410</div> 3411</div> 3412<div class="paragraph"> 3413<p>Starting with Boost release 1.33.0, <code>shared_ptr</code> uses a lock-free implementation on most common platforms.</p> 3414</div> 3415<div class="paragraph"> 3416<p>If your program is single-threaded and does not link to any libraries that might have used <code>shared_ptr</code> in its default configuration, 3417you can <code>#define</code> the macro <code>BOOST_SP_DISABLE_THREADS</code> on a project-wide basis to switch to ordinary non-atomic reference count updates.</p> 3418</div> 3419<div class="paragraph"> 3420<p>(Defining <code>BOOST_SP_DISABLE_THREADS</code> in some, but not all, translation units is technically a violation of the One Definition Rule and 3421undefined behavior. Nevertheless, the implementation attempts to do its best to accommodate the request to use non-atomic updates in those 3422translation units. No guarantees, though.)</p> 3423</div> 3424<div class="paragraph"> 3425<p>You can define the macro <code>BOOST_SP_USE_PTHREADS</code> to turn off the lock-free platform-specific implementation and fall back to the generic 3426<code>pthread_mutex_t</code>-based code.</p> 3427</div> 3428</div> 3429<div class="sect2"> 3430<h3 id="shared_ptr_frequently_asked_questions">Frequently Asked Questions</h3> 3431<div class="qlist qanda"> 3432<ol> 3433<li> 3434<p><em>There are several variations of shared pointers, with different tradeoffs; why does the smart pointer library supply only a single implementation? It would be useful to be able to experiment with each type so as to find the most suitable for the job at hand?</em></p> 3435<p>An important goal of <code>shared_ptr</code> is to provide a standard shared-ownership pointer. Having a single pointer type is important for stable 3436library interfaces, since different shared pointers typically cannot interoperate, i.e. a reference counted pointer (used by library A) 3437cannot share ownership with a linked pointer (used by library B.)</p> 3438</li> 3439<li> 3440<p><em>Why doesn’t shared_ptr have template parameters supplying traits or policies to allow extensive user customization?</em></p> 3441<p>Parameterization discourages users. The <code>shared_ptr</code> template is carefully crafted to meet common needs without extensive parameterization.</p> 3442</li> 3443<li> 3444<p><em>I am not convinced. Default parameters can be used where appropriate to hide the complexity. Again, why not policies?</em></p> 3445<p>Template parameters affect the type. See the answer to the first question above.</p> 3446</li> 3447<li> 3448<p><em>Why doesn’t <code>shared_ptr</code> use a linked list implementation?</em></p> 3449<p>A linked list implementation does not offer enough advantages to offset the added cost of an extra pointer. In addition, it is expensive to 3450make a linked list implementation thread safe.</p> 3451</li> 3452<li> 3453<p><em>Why doesn’t <code>shared_ptr</code> (or any of the other Boost smart pointers) supply an automatic conversion to T*?</em></p> 3454<p>Automatic conversion is believed to be too error prone.</p> 3455</li> 3456<li> 3457<p><em>Why does <code>shared_ptr</code> supply <code>use_count()</code>?</em></p> 3458<p>As an aid to writing test cases and debugging displays. One of the progenitors had <code>use_count()</code>, and it was useful in tracking down bugs in 3459a complex project that turned out to have cyclic-dependencies.</p> 3460</li> 3461<li> 3462<p><em>Why doesn’t <code>shared_ptr</code> specify complexity requirements?</em></p> 3463<p>Because complexity requirements limit implementors and complicate the specification without apparent benefit to <code>shared_ptr</code> users. For example, 3464error-checking implementations might become non-conforming if they had to meet stringent complexity requirements.</p> 3465</li> 3466<li> 3467<p><em>Why doesn’t <code>shared_ptr</code> provide a <code>release()</code> function?</em></p> 3468<p><code>shared_ptr</code> cannot give away ownership unless it’s <code>unique()</code> because the other copy will still destroy the object.</p> 3469<div class="paragraph"> 3470<p>Consider:</p> 3471</div> 3472<div class="listingblock"> 3473<div class="content"> 3474<pre class="highlight"><code>shared_ptr<int> a(new int); 3475shared_ptr<int> b(a); // a.use_count() == b.use_count() == 2 3476 3477int * p = a.release(); 3478 3479// Who owns p now? b will still call delete on it in its destructor.</code></pre> 3480</div> 3481</div> 3482<div class="paragraph"> 3483<p>Furthermore, the pointer returned by <code>release()</code> would be difficult to deallocate reliably, as the source <code>shared_ptr</code> could have been created with a 3484custom deleter, or may have pointed to an object of a different type.</p> 3485</div> 3486</li> 3487<li> 3488<p><em>Why is <code>operator->()</code> const, but its return value is a non-const pointer to the element type?</em></p> 3489<p>Shallow copy pointers, including raw pointers, typically don’t propagate constness. It makes little sense for them to do so, as you can always obtain a 3490non-const pointer from a const one and then proceed to modify the object through it. <code>shared_ptr</code> is "as close to raw pointers as possible but no closer".</p> 3491</li> 3492</ol> 3493</div> 3494</div> 3495</div> 3496</div> 3497<div class="sect1"> 3498<h2 id="weak_ptr">weak_ptr: Non-owning Observer</h2> 3499<div class="sectionbody"> 3500<div class="sect2"> 3501<h3 id="weak_ptr_description">Description</h3> 3502<div class="paragraph"> 3503<p>The <code>weak_ptr</code> class template stores a "weak reference" to an object that’s already managed by a <code>shared_ptr</code>. 3504To access the object, a <code>weak_ptr</code> can be converted to a <code>shared_ptr</code> using the <code>shared_ptr</code> constructor taking 3505<code>weak_ptr</code>, or the <code>weak_ptr</code> member function <code>lock</code>. When the last <code>shared_ptr</code> to the object goes away and the 3506object is deleted, the attempt to obtain a <code>shared_ptr</code> from the <code>weak_ptr</code> instances that refer to the deleted 3507object will fail: the constructor will throw an exception of type <code>boost::bad_weak_ptr</code>, and <code>weak_ptr::lock</code> will 3508return an empty <code>shared_ptr</code>.</p> 3509</div> 3510<div class="paragraph"> 3511<p>Every <code>weak_ptr</code> meets the <code>CopyConstructible</code> and <code>Assignable</code> requirements of the C++ Standard Library, and so 3512can be used in standard library containers. Comparison operators are supplied so that <code>weak_ptr</code> works with the standard 3513library’s associative containers.</p> 3514</div> 3515<div class="paragraph"> 3516<p><code>weak_ptr</code> operations never throw exceptions.</p> 3517</div> 3518<div class="paragraph"> 3519<p>The class template is parameterized on <code>T</code>, the type of the object pointed to.</p> 3520</div> 3521<div class="paragraph"> 3522<p>Compared to <code>shared_ptr</code>, <code>weak_ptr</code> provides a very limited subset of operations since accessing its stored pointer is 3523often dangerous in multithreaded programs, and sometimes unsafe even within a single thread (that is, it may invoke undefined 3524behavior.) Pretend for a moment that <code>weak_ptr</code> had a get member function that returned a raw pointer, and consider this innocent 3525piece of code:</p> 3526</div> 3527<div class="listingblock"> 3528<div class="content"> 3529<pre class="highlight"><code>shared_ptr<int> p(new int(5)); 3530weak_ptr<int> q(p); 3531 3532// some time later 3533 3534if(int * r = q.get()) 3535{ 3536 // use *r 3537}</code></pre> 3538</div> 3539</div> 3540<div class="paragraph"> 3541<p>Imagine that after the <code>if</code>, but immediately before <code>r</code> is used, another thread executes the statement <code>p.reset()</code>. Now <code>r</code> is a dangling pointer.</p> 3542</div> 3543<div class="paragraph"> 3544<p>The solution to this problem is to create a temporary <code>shared_ptr</code> from <code>q</code>:</p> 3545</div> 3546<div class="listingblock"> 3547<div class="content"> 3548<pre class="highlight"><code>shared_ptr<int> p(new int(5)); 3549weak_ptr<int> q(p); 3550 3551// some time later 3552 3553if(shared_ptr<int> r = q.lock()) 3554{ 3555 // use *r 3556}</code></pre> 3557</div> 3558</div> 3559<div class="paragraph"> 3560<p>Now <code>r</code> holds a reference to the object that was pointed by <code>q</code>. Even if <code>p.reset()</code> is executed in another thread, the object will stay alive until 3561<code>r</code> goes out of scope or is reset. By obtaining a <code>shared_ptr</code> to the object, we have effectively locked it against destruction.</p> 3562</div> 3563</div> 3564<div class="sect2"> 3565<h3 id="weak_ptr_synopsis">Synopsis</h3> 3566<div class="paragraph"> 3567<p><code>weak_ptr</code> is defined in <code><boost/smart_ptr/weak_ptr.hpp></code>.</p> 3568</div> 3569<div class="listingblock"> 3570<div class="content"> 3571<pre class="highlight"><code>namespace boost { 3572 3573 template<class T> class weak_ptr { 3574 public: 3575 3576 typedef /*see below*/ element_type; 3577 3578 weak_ptr() noexcept; 3579 3580 template<class Y> weak_ptr(shared_ptr<Y> const & r) noexcept; 3581 weak_ptr(weak_ptr const & r) noexcept; 3582 template<class Y> weak_ptr(weak_ptr<Y> const & r) noexcept; 3583 3584 weak_ptr(weak_ptr && r) noexcept; 3585 3586 template<class Y> weak_ptr(shared_ptr<Y> const & r, element_type * p) noexcept; 3587 template<class Y> weak_ptr(weak_ptr<Y> const & r, element_type * p) noexcept; 3588 template<class Y> weak_ptr(weak_ptr<Y> && r, element_type * p) noexcept; 3589 3590 ~weak_ptr() noexcept; 3591 3592 weak_ptr & operator=(weak_ptr const & r) noexcept; 3593 weak_ptr & operator=(weak_ptr && r) noexcept; 3594 template<class Y> weak_ptr & operator=(weak_ptr<Y> const & r) noexcept; 3595 template<class Y> weak_ptr & operator=(shared_ptr<Y> const & r) noexcept; 3596 3597 long use_count() const noexcept; 3598 bool expired() const noexcept; 3599 3600 bool empty() const noexcept; 3601 3602 shared_ptr<T> lock() const noexcept; 3603 3604 void reset() noexcept; 3605 3606 void swap(weak_ptr<T> & b) noexcept; 3607 3608 template<class Y> bool owner_before( weak_ptr<Y> const & r ) const noexcept; 3609 template<class Y> bool owner_before( shared_ptr<Y> const & r ) const noexcept; 3610 3611 template<class Y> bool owner_equals( weak_ptr<Y> const & r ) const noexcept; 3612 template<class Y> bool owner_equals( shared_ptr<Y> const & r ) const noexcept; 3613 3614 std::size_t owner_hash_value() const noexcept; 3615 }; 3616 3617 template<class T, class U> 3618 bool operator<(weak_ptr<T> const & a, weak_ptr<U> const & b) noexcept; 3619 3620 template<class T> void swap(weak_ptr<T> & a, weak_ptr<T> & b) noexcept; 3621}</code></pre> 3622</div> 3623</div> 3624</div> 3625<div class="sect2"> 3626<h3 id="weak_ptr_members">Members</h3> 3627<div class="sect3"> 3628<h4 id="weak_ptr_element_type">element_type</h4> 3629<div class="listingblock"> 3630<div class="content"> 3631<pre class="highlight"><code>typedef ... element_type;</code></pre> 3632</div> 3633</div> 3634<div class="paragraph"> 3635<p><code>element_type</code> is <code>T</code> when <code>T</code> is not an array type, and <code>U</code> when <code>T</code> is <code>U[]</code> or <code>U[N]</code>.</p> 3636</div> 3637</div> 3638<div class="sect3"> 3639<h4 id="weak_ptr_constructors">constructors</h4> 3640<div class="listingblock"> 3641<div class="content"> 3642<pre class="highlight"><code>weak_ptr() noexcept;</code></pre> 3643</div> 3644</div> 3645<div class="ulist none"> 3646<ul class="none"> 3647<li> 3648<p></p> 3649<div class="dlist"> 3650<dl> 3651<dt class="hdlist1">Effects</dt> 3652<dd> 3653<p>Constructs an empty <code>weak_ptr</code>.</p> 3654</dd> 3655<dt class="hdlist1">Postconditions</dt> 3656<dd> 3657<p><code>use_count() == 0</code>.</p> 3658</dd> 3659</dl> 3660</div> 3661</li> 3662</ul> 3663</div> 3664<div class="listingblock"> 3665<div class="content"> 3666<pre class="highlight"><code>template<class Y> weak_ptr(shared_ptr<Y> const & r) noexcept;</code></pre> 3667</div> 3668</div> 3669<div class="listingblock"> 3670<div class="content"> 3671<pre class="highlight"><code>weak_ptr(weak_ptr const & r) noexcept;</code></pre> 3672</div> 3673</div> 3674<div class="listingblock"> 3675<div class="content"> 3676<pre class="highlight"><code>template<class Y> weak_ptr(weak_ptr<Y> const & r) noexcept;</code></pre> 3677</div> 3678</div> 3679<div class="ulist none"> 3680<ul class="none"> 3681<li> 3682<p></p> 3683<div class="dlist"> 3684<dl> 3685<dt class="hdlist1">Effects</dt> 3686<dd> 3687<p>If <code>r</code> is empty, constructs an empty <code>weak_ptr</code>; otherwise, constructs a <code>weak_ptr</code> that shares ownership with <code>r</code> as if by storing a copy of the pointer stored in <code>r</code>.</p> 3688</dd> 3689<dt class="hdlist1">Postconditions</dt> 3690<dd> 3691<p><code>use_count() == r.use_count()</code>.</p> 3692</dd> 3693</dl> 3694</div> 3695</li> 3696</ul> 3697</div> 3698<div class="listingblock"> 3699<div class="content"> 3700<pre class="highlight"><code>weak_ptr(weak_ptr && r) noexcept;</code></pre> 3701</div> 3702</div> 3703<div class="ulist none"> 3704<ul class="none"> 3705<li> 3706<p></p> 3707<div class="dlist"> 3708<dl> 3709<dt class="hdlist1">Effects</dt> 3710<dd> 3711<p>Constructs a <code>weak_ptr</code> that has the value <code>r</code> held.</p> 3712</dd> 3713<dt class="hdlist1">Postconditions</dt> 3714<dd> 3715<p><code>r</code> is empty.</p> 3716</dd> 3717</dl> 3718</div> 3719</li> 3720</ul> 3721</div> 3722</div> 3723<div class="sect3"> 3724<h4 id="weak_ptr_aliasing_constructors">aliasing constructors</h4> 3725<div class="listingblock"> 3726<div class="content"> 3727<pre class="highlight"><code>template<class Y> weak_ptr(shared_ptr<Y> const & r, element_type * p) noexcept;</code></pre> 3728</div> 3729</div> 3730<div class="listingblock"> 3731<div class="content"> 3732<pre class="highlight"><code>template<class Y> weak_ptr(weak_ptr<Y> const & r, element_type * p) noexcept;</code></pre> 3733</div> 3734</div> 3735<div class="listingblock"> 3736<div class="content"> 3737<pre class="highlight"><code>template<class Y> weak_ptr(weak_ptr<Y> && r, element_type * p) noexcept;</code></pre> 3738</div> 3739</div> 3740<div class="dlist"> 3741<dl> 3742<dt class="hdlist1">Effects</dt> 3743<dd> 3744<p>Constructs a <code>weak_ptr</code> from <code>r</code> as if by using the corresponding converting/copy/move constructor, but stores <code>p</code> instead.</p> 3745</dd> 3746<dt class="hdlist1">Postconditions</dt> 3747<dd> 3748<p><code>use_count() == r.use_count()</code>. When <code>!expired()</code>, <code>shared_ptr<T>(*this).get() == p</code>.</p> 3749</dd> 3750</dl> 3751</div> 3752<div class="admonitionblock note"> 3753<table> 3754<tr> 3755<td class="icon"> 3756<div class="title">Note</div> 3757</td> 3758<td class="content"> 3759These constructors are an extension, not present in <code>std::weak_ptr</code>. 3760</td> 3761</tr> 3762</table> 3763</div> 3764</div> 3765<div class="sect3"> 3766<h4 id="weak_ptr_destructor">destructor</h4> 3767<div class="listingblock"> 3768<div class="content"> 3769<pre class="highlight"><code>~weak_ptr() noexcept;</code></pre> 3770</div> 3771</div> 3772<div class="ulist none"> 3773<ul class="none"> 3774<li> 3775<p></p> 3776<div class="dlist"> 3777<dl> 3778<dt class="hdlist1">Effects</dt> 3779<dd> 3780<p>Destroys this <code>weak_ptr</code> but has no effect on the object its stored pointer points to.</p> 3781</dd> 3782</dl> 3783</div> 3784</li> 3785</ul> 3786</div> 3787</div> 3788<div class="sect3"> 3789<h4 id="weak_ptr_assignment">assignment</h4> 3790<div class="listingblock"> 3791<div class="content"> 3792<pre class="highlight"><code>weak_ptr & operator=(weak_ptr const & r) noexcept;</code></pre> 3793</div> 3794</div> 3795<div class="listingblock"> 3796<div class="content"> 3797<pre class="highlight"><code>weak_ptr & operator=(weak_ptr && r) noexcept;</code></pre> 3798</div> 3799</div> 3800<div class="listingblock"> 3801<div class="content"> 3802<pre class="highlight"><code>template<class Y> weak_ptr & operator=(weak_ptr<Y> const & r) noexcept;</code></pre> 3803</div> 3804</div> 3805<div class="listingblock"> 3806<div class="content"> 3807<pre class="highlight"><code>template<class Y> weak_ptr & operator=(shared_ptr<Y> const & r) noexcept;</code></pre> 3808</div> 3809</div> 3810<div class="ulist none"> 3811<ul class="none"> 3812<li> 3813<p></p> 3814<div class="dlist"> 3815<dl> 3816<dt class="hdlist1">Effects</dt> 3817<dd> 3818<p>Equivalent to <code>weak_ptr(r).swap(*this)</code>.</p> 3819</dd> 3820</dl> 3821</div> 3822</li> 3823</ul> 3824</div> 3825<div class="admonitionblock note"> 3826<table> 3827<tr> 3828<td class="icon"> 3829<div class="title">Note</div> 3830</td> 3831<td class="content"> 3832The implementation is free to meet the effects (and the implied guarantees) via different means, without creating a temporary. 3833</td> 3834</tr> 3835</table> 3836</div> 3837</div> 3838<div class="sect3"> 3839<h4 id="weak_ptr_use_count">use_count</h4> 3840<div class="listingblock"> 3841<div class="content"> 3842<pre class="highlight"><code>long use_count() const noexcept;</code></pre> 3843</div> 3844</div> 3845<div class="ulist none"> 3846<ul class="none"> 3847<li> 3848<p></p> 3849<div class="dlist"> 3850<dl> 3851<dt class="hdlist1">Returns</dt> 3852<dd> 3853<p>0 if <code>*this</code> is empty; otherwise, the number of <code>shared_ptr</code> objects that share ownership with <code>*this</code>.</p> 3854</dd> 3855</dl> 3856</div> 3857</li> 3858</ul> 3859</div> 3860</div> 3861<div class="sect3"> 3862<h4 id="weak_ptr_expired">expired</h4> 3863<div class="listingblock"> 3864<div class="content"> 3865<pre class="highlight"><code>bool expired() const noexcept;</code></pre> 3866</div> 3867</div> 3868<div class="ulist none"> 3869<ul class="none"> 3870<li> 3871<p></p> 3872<div class="dlist"> 3873<dl> 3874<dt class="hdlist1">Returns</dt> 3875<dd> 3876<p><code>use_count() == 0</code>.</p> 3877</dd> 3878</dl> 3879</div> 3880</li> 3881</ul> 3882</div> 3883</div> 3884<div class="sect3"> 3885<h4 id="weak_ptr_empty">empty</h4> 3886<div class="listingblock"> 3887<div class="content"> 3888<pre class="highlight"><code>bool empty() const noexcept;</code></pre> 3889</div> 3890</div> 3891<div class="ulist none"> 3892<ul class="none"> 3893<li> 3894<p></p> 3895<div class="dlist"> 3896<dl> 3897<dt class="hdlist1">Returns</dt> 3898<dd> 3899<p><code>true</code> when <code>*this</code> is empty, <code>false</code> otherwise.</p> 3900</dd> 3901</dl> 3902</div> 3903</li> 3904</ul> 3905</div> 3906<div class="admonitionblock note"> 3907<table> 3908<tr> 3909<td class="icon"> 3910<div class="title">Note</div> 3911</td> 3912<td class="content"> 3913This function is an extension, not present in <code>std::weak_ptr</code>. 3914</td> 3915</tr> 3916</table> 3917</div> 3918</div> 3919<div class="sect3"> 3920<h4 id="weak_ptr_lock">lock</h4> 3921<div class="listingblock"> 3922<div class="content"> 3923<pre class="highlight"><code>shared_ptr<T> lock() const noexcept;</code></pre> 3924</div> 3925</div> 3926<div class="ulist none"> 3927<ul class="none"> 3928<li> 3929<p></p> 3930<div class="dlist"> 3931<dl> 3932<dt class="hdlist1">Returns</dt> 3933<dd> 3934<p><code>expired()? shared_ptr<T>(): shared_ptr<T>(*this)</code>.</p> 3935</dd> 3936</dl> 3937</div> 3938</li> 3939</ul> 3940</div> 3941</div> 3942<div class="sect3"> 3943<h4 id="weak_ptr_reset">reset</h4> 3944<div class="listingblock"> 3945<div class="content"> 3946<pre class="highlight"><code>void reset() noexcept;</code></pre> 3947</div> 3948</div> 3949<div class="ulist none"> 3950<ul class="none"> 3951<li> 3952<p></p> 3953<div class="dlist"> 3954<dl> 3955<dt class="hdlist1">Effects</dt> 3956<dd> 3957<p>Equivalent to <code>weak_ptr().swap(*this)</code>.</p> 3958</dd> 3959</dl> 3960</div> 3961</li> 3962</ul> 3963</div> 3964</div> 3965<div class="sect3"> 3966<h4 id="weak_ptr_swap">swap</h4> 3967<div class="listingblock"> 3968<div class="content"> 3969<pre class="highlight"><code>void swap(weak_ptr & b) noexcept;</code></pre> 3970</div> 3971</div> 3972<div class="ulist none"> 3973<ul class="none"> 3974<li> 3975<p></p> 3976<div class="dlist"> 3977<dl> 3978<dt class="hdlist1">Effects</dt> 3979<dd> 3980<p>Exchanges the contents of the two smart pointers.</p> 3981</dd> 3982</dl> 3983</div> 3984</li> 3985</ul> 3986</div> 3987</div> 3988<div class="sect3"> 3989<h4 id="weak_ptr_owner_before">owner_before</h4> 3990<div class="listingblock"> 3991<div class="content"> 3992<pre class="highlight"><code>template<class Y> bool owner_before( weak_ptr<Y> const & r ) const noexcept;</code></pre> 3993</div> 3994</div> 3995<div class="listingblock"> 3996<div class="content"> 3997<pre class="highlight"><code>template<class Y> bool owner_before( shared_ptr<Y> const & r ) const noexcept;</code></pre> 3998</div> 3999</div> 4000<div class="ulist none"> 4001<ul class="none"> 4002<li> 4003<p></p> 4004<div class="dlist"> 4005<dl> 4006<dt class="hdlist1">Returns</dt> 4007<dd> 4008<p>See the description of <code>operator<</code>.</p> 4009</dd> 4010</dl> 4011</div> 4012</li> 4013</ul> 4014</div> 4015</div> 4016<div class="sect3"> 4017<h4 id="weak_ptr_owner_equals">owner_equals</h4> 4018<div class="listingblock"> 4019<div class="content"> 4020<pre class="highlight"><code>template<class Y> bool owner_equals( weak_ptr<Y> const & r ) const noexcept;</code></pre> 4021</div> 4022</div> 4023<div class="listingblock"> 4024<div class="content"> 4025<pre class="highlight"><code>template<class Y> bool owner_equals( shared_ptr<Y> const & r ) const noexcept;</code></pre> 4026</div> 4027</div> 4028<div class="ulist none"> 4029<ul class="none"> 4030<li> 4031<p></p> 4032<div class="dlist"> 4033<dl> 4034<dt class="hdlist1">Returns</dt> 4035<dd> 4036<p><code>true</code> if and only if <code>*this</code> and <code>r</code> share ownership or are both empty.</p> 4037</dd> 4038</dl> 4039</div> 4040</li> 4041</ul> 4042</div> 4043</div> 4044<div class="sect3"> 4045<h4 id="weak_ptr_owner_hash_value">owner_hash_value</h4> 4046<div class="listingblock"> 4047<div class="content"> 4048<pre class="highlight"><code>std::size_t owner_hash_value() const noexcept;</code></pre> 4049</div> 4050</div> 4051<div class="ulist none"> 4052<ul class="none"> 4053<li> 4054<p></p> 4055<div class="dlist"> 4056<dl> 4057<dt class="hdlist1">Returns</dt> 4058<dd> 4059<p>An unspecified hash value such that two instances that share ownership 4060have the same hash value.</p> 4061</dd> 4062</dl> 4063</div> 4064</li> 4065</ul> 4066</div> 4067</div> 4068</div> 4069<div class="sect2"> 4070<h3 id="weak_ptr_free_functions">Free Functions</h3> 4071<div class="sect3"> 4072<h4 id="weak_ptr_comparison">comparison</h4> 4073<div class="listingblock"> 4074<div class="content"> 4075<pre class="highlight"><code>template<class T, class U> 4076 bool operator<(weak_ptr<T> const & a, weak_ptr<U> const & b) noexcept;</code></pre> 4077</div> 4078</div> 4079<div class="ulist none"> 4080<ul class="none"> 4081<li> 4082<p></p> 4083<div class="dlist"> 4084<dl> 4085<dt class="hdlist1">Returns</dt> 4086<dd> 4087<p>An unspecified value such that</p> 4088<div class="ulist"> 4089<ul> 4090<li> 4091<p><code>operator<</code> is a strict weak ordering as described in section [lib.alg.sorting] of the C++ standard;</p> 4092</li> 4093<li> 4094<p>under the equivalence relation defined by <code>operator<</code>, <code>!(a < b) && !(b < a)</code>, two <code>weak_ptr</code> instances 4095are equivalent if and only if they share ownership or are both empty.</p> 4096</li> 4097</ul> 4098</div> 4099</dd> 4100</dl> 4101</div> 4102</li> 4103</ul> 4104</div> 4105<div class="admonitionblock note"> 4106<table> 4107<tr> 4108<td class="icon"> 4109<div class="title">Note</div> 4110</td> 4111<td class="content"> 4112Allows <code>weak_ptr</code> objects to be used as keys in associative containers. 4113</td> 4114</tr> 4115</table> 4116</div> 4117</div> 4118<div class="sect3"> 4119<h4 id="weak_ptr_swap_2">swap</h4> 4120<div class="listingblock"> 4121<div class="content"> 4122<pre class="highlight"><code>template<class T> void swap(weak_ptr<T> & a, weak_ptr<T> & b) noexcept;</code></pre> 4123</div> 4124</div> 4125<div class="ulist none"> 4126<ul class="none"> 4127<li> 4128<p></p> 4129<div class="dlist"> 4130<dl> 4131<dt class="hdlist1">Effects</dt> 4132<dd> 4133<p>Equivalent to <code>a.swap(b)</code>.</p> 4134</dd> 4135</dl> 4136</div> 4137</li> 4138</ul> 4139</div> 4140</div> 4141</div> 4142<div class="sect2"> 4143<h3 id="weak_ptr_frequently_asked_questions">Frequently Asked Questions</h3> 4144<div class="qlist qanda"> 4145<ol> 4146<li> 4147<p><em>Can an object create a weak_ptr to itself in its constructor?</em></p> 4148<p>No. A <code>weak_ptr</code> can only be created from a <code>shared_ptr</code>, and at object construction time no 4149<code>shared_ptr</code> to the object exists yet. Even if you could create a temporary <code>shared_ptr</code> to <code>this</code>, 4150it would go out of scope at the end of the constructor, and all <code>weak_ptr</code> instances would instantly expire.</p> 4151<div class="paragraph"> 4152<p>The solution is to make the constructor private, and supply a factory function that returns a <code>shared_ptr</code>:</p> 4153</div> 4154<div class="listingblock"> 4155<div class="content"> 4156<pre class="highlight"><code>class X 4157{ 4158private: 4159 4160 X(); 4161 4162public: 4163 4164 static shared_ptr<X> create() 4165 { 4166 shared_ptr<X> px(new X); 4167 // create weak pointers from px here 4168 return px; 4169 } 4170};</code></pre> 4171</div> 4172</div> 4173</li> 4174</ol> 4175</div> 4176</div> 4177</div> 4178</div> 4179<div class="sect1"> 4180<h2 id="make_shared">make_shared: Creating shared_ptr</h2> 4181<div class="sectionbody"> 4182<div class="sect2"> 4183<h3 id="make_shared_description">Description</h3> 4184<div class="paragraph"> 4185<p>The function templates <code>make_shared</code> and <code>allocate_shared</code> provide convenient, 4186safe and efficient ways to create <code>shared_ptr</code> objects.</p> 4187</div> 4188</div> 4189<div class="sect2"> 4190<h3 id="make_shared_rationale">Rationale</h3> 4191<div class="paragraph"> 4192<p>Consistent use of <code>shared_ptr</code> can eliminate the need to use an explicit 4193<code>delete</code>, but alone it provides no support in avoiding explicit <code>new</code>. There 4194were repeated requests from users for a factory function that creates an 4195object of a given type and returns a <code>shared_ptr</code> to it. Besides convenience 4196and style, such a function is also exception safe and considerably faster 4197because it can use a single allocation for both the object and its 4198corresponding control block, eliminating a significant portion of 4199<code>shared_ptr</code> construction overhead. This eliminates one of the major 4200efficiency complaints about <code>shared_ptr</code>.</p> 4201</div> 4202<div class="paragraph"> 4203<p>The family of overloaded function templates, <code>make_shared</code> and 4204<code>allocate_shared</code>, were provided to address this need. <code>make_shared</code> uses the 4205global <code>operator new</code> to allocate memory, whereas <code>allocate_shared</code> uses an 4206user-supplied allocator, allowing finer control.</p> 4207</div> 4208<div class="paragraph"> 4209<p>The rationale for choosing the name <code>make_shared</code> is that the expression 4210<code>make_shared<Widget>()</code> can be read aloud and conveys the intended meaning.</p> 4211</div> 4212<div class="paragraph"> 4213<p>Originally the Boost function templates <code>allocate_shared</code> and <code>make_shared</code> 4214were provided for scalar objects only. There was a need to have efficient 4215allocation of array objects. One criticism of class template <code>shared_array</code> 4216was always the lack of a utility like <code>make_shared</code> that uses only a single 4217allocation. When <code>shared_ptr</code> was enhanced to support array types, additional 4218overloads of <code>allocate_shared</code> and <code>make_shared</code> were provided for array 4219types.</p> 4220</div> 4221</div> 4222<div class="sect2"> 4223<h3 id="make_shared_synopsis">Synopsis</h3> 4224<div class="paragraph"> 4225<p><code>make_shared</code> and <code>allocate_shared</code> are defined in 4226<code><boost/smart_ptr/make_shared.hpp></code>.</p> 4227</div> 4228<div class="listingblock"> 4229<div class="content"> 4230<pre class="highlight"><code>namespace boost { 4231 <code>// T is not an array</code> 4232 template<class T, class... Args> 4233 shared_ptr<T> make_shared(Args&&... args); 4234 template<class T, class A, class... Args> 4235 shared_ptr<T> allocate_shared(const A& a, Args&&... args); 4236 4237 <code>// T is an array of unknown bounds</code> 4238 template<class T> 4239 shared_ptr<T> make_shared(std::size_t n); 4240 template<class T, class A> 4241 shared_ptr<T> allocate_shared(const A& a, std::size_t n); 4242 4243 <code>// T is an array of known bounds</code> 4244 template<class T> 4245 shared_ptr<T> make_shared(); 4246 template<class T, class A> 4247 shared_ptr<T> allocate_shared(const A& a); 4248 4249 <code>// T is an array of unknown bounds</code> 4250 template<class T> shared_ptr<T> 4251 make_shared(std::size_t n, const remove_extent_t<T>& v); 4252 template<class T, class A> shared_ptr<T> 4253 allocate_shared(const A& a, std::size_t n, const remove_extent_t<T>& v); 4254 4255 <code>// T is an array of known bounds</code> 4256 template<class T> 4257 shared_ptr<T> make_shared(const remove_extent_t<T>& v); 4258 template<class T, class A> 4259 shared_ptr<T> allocate_shared(const A& a, const remove_extent_t<T>& v); 4260 4261 <code>// T is not an array of unknown bounds</code> 4262 template<class T> 4263 shared_ptr<T> make_shared_noinit(); 4264 template<class T, class A> 4265 shared_ptr<T> allocate_shared_noinit(const A& a); 4266 4267 <code>// T is an array of unknown bounds</code> 4268 template<class T> 4269 shared_ptr<T> make_shared_noinit(std::size_t n); 4270 template<class T, class A> 4271 shared_ptr<T> allocate_shared_noinit(const A& a, std::size_t n); 4272}</code></pre> 4273</div> 4274</div> 4275</div> 4276<div class="sect2"> 4277<h3 id="make_shared_common_requirements">Common Requirements</h3> 4278<div class="paragraph"> 4279<p>The common requirements that apply to all <code>make_shared</code> and <code>allocate_shared</code> 4280overloads, unless specified otherwise, are described below.</p> 4281</div> 4282<div class="dlist"> 4283<dl> 4284<dt class="hdlist1">Requires</dt> 4285<dd> 4286<p><code>A</code> shall be an <em>allocator</em>. The copy constructor and destructor 4287of <code>A</code> shall not throw exceptions.</p> 4288</dd> 4289<dt class="hdlist1">Effects</dt> 4290<dd> 4291<p>Allocates memory for an object of type <code>T</code> or <code>n</code> objects of <code>U</code> 4292(if <code>T</code> is an array type of the form <code>U[]</code> and <code>n</code> is determined by 4293arguments, as specified by the concrete overload). The object is initialized 4294from arguments as specified by the concrete overload. Uses a rebound copy of 4295<code>a</code> (for an unspecified <code>value_type</code>) to allocate memory. If an exception is 4296thrown, the functions have no effect.</p> 4297</dd> 4298<dt class="hdlist1">Returns</dt> 4299<dd> 4300<p>A <code>shared_ptr</code> instance that stores and owns the address of the 4301newly constructed object.</p> 4302</dd> 4303<dt class="hdlist1">Postconditions</dt> 4304<dd> 4305<p><code>r.get() != 0</code> and <code>r.use_count() == 1</code>, where <code>r</code> 4306is the return value.</p> 4307</dd> 4308<dt class="hdlist1">Throws</dt> 4309<dd> 4310<p><code>std::bad_alloc</code>, an exception thrown from <code>A::allocate</code>, or from the 4311initialization of the object.</p> 4312</dd> 4313<dt class="hdlist1">Remarks</dt> 4314<dd> 4315<div class="ulist"> 4316<ul> 4317<li> 4318<p>Performs no more than one memory allocation. This provides efficiency 4319equivalent to an intrusive smart pointer.</p> 4320</li> 4321<li> 4322<p>When an object of an array type is specified to be initialized to a value of 4323the same type <code>v</code>, this shall be interpreted to mean that each array element 4324of the object is initialized to the corresponding element from <code>v</code>.</p> 4325</li> 4326<li> 4327<p>When an object of an array type is specified to be value-initialized, this 4328shall be interpreted to mean that each array element of the object is 4329value-initialized.</p> 4330</li> 4331<li> 4332<p>When a (sub)object of non-array type <code>U</code> is specified to be initialized to 4333a value <code>v</code>, or constructed from <code>args...</code>, <code>make_shared</code> shall perform 4334this initialization via the expression <code>::new(p) U(expr)</code> (where 4335<code><em>expr</em></code> is <code>v</code> or <code>std::forward<Args>(args)...)</code> respectively) and <code>p</code> 4336has type <code>void*</code> and points to storage suitable to hold an object of type 4337<code>U</code>.</p> 4338</li> 4339<li> 4340<p>When a (sub)object of non-array type <code>U</code> is specified to be initialized to 4341a value <code>v</code>, or constructed from <code>args...</code>, <code>allocate_shared</code> shall 4342perform this initialization via the expression 4343<code>std::allocator_traits<A2>::construct(a2, p, expr)</code> (where 4344<code><em>expr</em></code> is <code>v</code> or <code>std::forward<Args>(args)...)</code> respectively), <code>p</code> 4345points to storage suitable to hold an object of type <code>U</code>, and <code>a2</code> of 4346type <code>A2</code> is a potentially rebound copy of <code>a</code>.</p> 4347</li> 4348<li> 4349<p>When a (sub)object of non-array type <code>U</code> is specified to be 4350default-initialized, <code>make_shared_noinit</code> and <code>allocate_shared_noinit</code> shall 4351perform this initialization via the expression <code>::new(p) U</code>, where 4352<code>p</code> has type <code>void*</code> and points to storage suitable to hold an object of 4353type <code>U</code>.</p> 4354</li> 4355<li> 4356<p>When a (sub)object of non-array type <code>U</code> is specified to be 4357value-initialized, <code>make_shared</code> shall perform this initialization via the 4358expression <code>::new(p) U()</code>, where <code>p</code> has type <code>void*</code> and points to 4359storage suitable to hold an object of type <code>U</code>.</p> 4360</li> 4361<li> 4362<p>When a (sub)object of non-array type <code>U</code> is specified to be 4363value-initialized, <code>allocate_shared</code> shall perform this initialization via the 4364expression <code>std::allocator_traits<A2>::construct(a2, p)</code>, where 4365<code>p</code> points to storage suitable to hold an object of type <code>U</code> and <code>a2</code> of 4366type <code>A2</code> is a potentially rebound copy of <code>a</code>.</p> 4367</li> 4368<li> 4369<p>Array elements are initialized in ascending order of their addresses.</p> 4370</li> 4371<li> 4372<p>When the lifetime of the object managed by the return value ends, or when 4373the initialization of an array element throws an exception, the initialized 4374elements should be destroyed in the reverse order of their construction.</p> 4375</li> 4376</ul> 4377</div> 4378</dd> 4379</dl> 4380</div> 4381<div class="admonitionblock note"> 4382<table> 4383<tr> 4384<td class="icon"> 4385<div class="title">Note</div> 4386</td> 4387<td class="content"> 4388These functions will typically allocate more memory than the total size 4389of the element objects to allow for internal bookkeeping structures such as 4390the reference counts. 4391</td> 4392</tr> 4393</table> 4394</div> 4395</div> 4396<div class="sect2"> 4397<h3 id="make_shared_free_functions">Free Functions</h3> 4398<div class="listingblock"> 4399<div class="content"> 4400<pre class="highlight"><code>template<class T, class... Args> 4401 shared_ptr<T> make_shared(Args&&... args);</code></pre> 4402</div> 4403</div> 4404<div class="listingblock"> 4405<div class="content"> 4406<pre class="highlight"><code>template<class T, class A, class... Args> 4407 shared_ptr<T> allocate_shared(const A& a, Args&&... args);</code></pre> 4408</div> 4409</div> 4410<div class="ulist none"> 4411<ul class="none"> 4412<li> 4413<p></p> 4414<div class="dlist"> 4415<dl> 4416<dt class="hdlist1">Constraints</dt> 4417<dd> 4418<p><code>T</code> is not an array.</p> 4419</dd> 4420<dt class="hdlist1">Returns</dt> 4421<dd> 4422<p>A <code>shared_ptr</code> to an object of type <code>T</code>, constructed from 4423<code>args...</code>.</p> 4424</dd> 4425<dt class="hdlist1">Examples</dt> 4426</dl> 4427</div> 4428</li> 4429<li> 4430<p><code>auto p = make_shared<int>();</code></p> 4431</li> 4432<li> 4433<p><code>auto p = make_shared<std::vector<int> >(16, 1);</code></p> 4434</li> 4435</ul> 4436</div> 4437<div class="listingblock"> 4438<div class="content"> 4439<pre class="highlight"><code>template<class T> 4440 shared_ptr<T> make_shared(std::size_t n);</code></pre> 4441</div> 4442</div> 4443<div class="listingblock"> 4444<div class="content"> 4445<pre class="highlight"><code>template<class T, class A> 4446 shared_ptr<T> allocate_shared(const A& a, std::size_t n);</code></pre> 4447</div> 4448</div> 4449<div class="ulist none"> 4450<ul class="none"> 4451<li> 4452<p></p> 4453<div class="dlist"> 4454<dl> 4455<dt class="hdlist1">Constraints</dt> 4456<dd> 4457<p><code>T</code> is an array of unknown bounds.</p> 4458</dd> 4459<dt class="hdlist1">Returns</dt> 4460<dd> 4461<p>A <code>shared_ptr</code> to a sequence of <code>n</code> value-initialized objects of 4462type <code>remove_extent_t<T></code>.</p> 4463</dd> 4464<dt class="hdlist1">Examples</dt> 4465</dl> 4466</div> 4467</li> 4468<li> 4469<p><code>auto p = make_shared<double[]>(1024);</code></p> 4470</li> 4471<li> 4472<p><code>auto p = make_shared<double[][2][2]>(6);</code></p> 4473</li> 4474</ul> 4475</div> 4476<div class="listingblock"> 4477<div class="content"> 4478<pre class="highlight"><code>template<class T> 4479 shared_ptr<T> make_shared();</code></pre> 4480</div> 4481</div> 4482<div class="listingblock"> 4483<div class="content"> 4484<pre class="highlight"><code>template<class T, class A> 4485 shared_ptr<T> allocate_shared(const A& a);</code></pre> 4486</div> 4487</div> 4488<div class="ulist none"> 4489<ul class="none"> 4490<li> 4491<p></p> 4492<div class="dlist"> 4493<dl> 4494<dt class="hdlist1">Constraints</dt> 4495<dd> 4496<p><code>T</code> is an array of known bounds.</p> 4497</dd> 4498<dt class="hdlist1">Returns</dt> 4499<dd> 4500<p>A <code>shared_ptr</code> to a sequence of <code>extent_v<T></code> value-initialized 4501objects of type <code>remove_extent_t<T></code>.</p> 4502</dd> 4503<dt class="hdlist1">Examples</dt> 4504</dl> 4505</div> 4506</li> 4507<li> 4508<p><code>auto p = make_shared<double[1024]>();</code></p> 4509</li> 4510<li> 4511<p><code>auto p = make_shared<double[6][2][2]>();</code></p> 4512</li> 4513</ul> 4514</div> 4515<div class="listingblock"> 4516<div class="content"> 4517<pre class="highlight"><code>template<class T> shared_ptr<T> 4518 make_shared(std::size_t n, const remove_extent_t<T>& v);</code></pre> 4519</div> 4520</div> 4521<div class="listingblock"> 4522<div class="content"> 4523<pre class="highlight"><code>template<class T, class A> shared_ptr<T> 4524 allocate_shared(const A& a, std::size_t n, const remove_extent_t<T>& v);</code></pre> 4525</div> 4526</div> 4527<div class="ulist none"> 4528<ul class="none"> 4529<li> 4530<p></p> 4531<div class="dlist"> 4532<dl> 4533<dt class="hdlist1">Constraints</dt> 4534<dd> 4535<p><code>T</code> is an array of unknown bounds.</p> 4536</dd> 4537<dt class="hdlist1">Returns</dt> 4538<dd> 4539<p>A <code>shared_ptr</code> to a sequence of <code>n</code> objects of type 4540<code>remove_extent_t<T></code>, each initialized to <code>v</code>.</p> 4541</dd> 4542<dt class="hdlist1">Examples</dt> 4543</dl> 4544</div> 4545</li> 4546<li> 4547<p><code>auto p = make_shared<double[]>(1024, 1.0);</code></p> 4548</li> 4549<li> 4550<p><code>auto p = make_shared<double[][2]>(6, {1.0, 0.0});</code></p> 4551</li> 4552<li> 4553<p><code>auto p = make_shared<std::vector<int>[]>(4, {1, 2});</code></p> 4554</li> 4555</ul> 4556</div> 4557<div class="listingblock"> 4558<div class="content"> 4559<pre class="highlight"><code>template<class T> 4560 shared_ptr<T> make_shared(const remove_extent_t<T>& v);</code></pre> 4561</div> 4562</div> 4563<div class="listingblock"> 4564<div class="content"> 4565<pre class="highlight"><code>template<class T, class A> 4566 shared_ptr<T> allocate_shared(const A& a, const remove_extent_t<T>& v);</code></pre> 4567</div> 4568</div> 4569<div class="ulist none"> 4570<ul class="none"> 4571<li> 4572<p></p> 4573<div class="dlist"> 4574<dl> 4575<dt class="hdlist1">Constraints</dt> 4576<dd> 4577<p><code>T</code> is an array of known bounds.</p> 4578</dd> 4579<dt class="hdlist1">Returns</dt> 4580<dd> 4581<p>A <code>shared_ptr</code> to a sequence of <code>extent_v<T></code> objects of type 4582<code>remove_extent_t<T></code>, each initialized to <code>v</code>.</p> 4583</dd> 4584<dt class="hdlist1">Examples</dt> 4585</dl> 4586</div> 4587</li> 4588<li> 4589<p><code>auto p = make_shared<double[1024]>(1.0);</code></p> 4590</li> 4591<li> 4592<p><code>auto p = make_shared<double[6][2]>({1.0, 0.0});</code></p> 4593</li> 4594<li> 4595<p><code>auto p = make_shared<std::vector<int>[4]>({1, 2});</code></p> 4596</li> 4597</ul> 4598</div> 4599<div class="listingblock"> 4600<div class="content"> 4601<pre class="highlight"><code>template<class T> 4602 shared_ptr<T> make_shared_noinit();</code></pre> 4603</div> 4604</div> 4605<div class="listingblock"> 4606<div class="content"> 4607<pre class="highlight"><code>template<class T, class A> 4608 shared_ptr<T> allocate_shared_noinit(const A& a);</code></pre> 4609</div> 4610</div> 4611<div class="ulist none"> 4612<ul class="none"> 4613<li> 4614<p></p> 4615<div class="dlist"> 4616<dl> 4617<dt class="hdlist1">Constraints</dt> 4618<dd> 4619<p><code>T</code> is not an array, or is an array of known bounds.</p> 4620</dd> 4621<dt class="hdlist1">Returns</dt> 4622<dd> 4623<p>A <code>shared_ptr</code> to a default-initialized object of type <code>T</code>, or a 4624sequence of <code>extent_v<T></code> default-initialized objects of type 4625<code>remove_extent_t<T></code>, respectively.</p> 4626</dd> 4627<dt class="hdlist1">Example</dt> 4628<dd> 4629<p><code>auto p = make_shared_noinit<double[1024]>();</code></p> 4630</dd> 4631</dl> 4632</div> 4633</li> 4634</ul> 4635</div> 4636<div class="listingblock"> 4637<div class="content"> 4638<pre class="highlight"><code>template<class T> 4639 shared_ptr<T> make_shared_noinit(std::size_t n);</code></pre> 4640</div> 4641</div> 4642<div class="listingblock"> 4643<div class="content"> 4644<pre class="highlight"><code>template<class T, class A> 4645 shared_ptr<T> allocate_shared_noinit(const A& a, std::size_t n);</code></pre> 4646</div> 4647</div> 4648<div class="ulist none"> 4649<ul class="none"> 4650<li> 4651<p></p> 4652<div class="dlist"> 4653<dl> 4654<dt class="hdlist1">Constraints</dt> 4655<dd> 4656<p><code>T</code> is an array of unknown bounds.</p> 4657</dd> 4658<dt class="hdlist1">Returns</dt> 4659<dd> 4660<p>A <code>shared_ptr</code> to a sequence of <code><em>n</em></code> default-initialized objects 4661of type <code>remove_extent_t<T></code>.</p> 4662</dd> 4663<dt class="hdlist1">Example</dt> 4664<dd> 4665<p><code>auto p = make_shared_noinit<double[]>(1024);</code></p> 4666</dd> 4667</dl> 4668</div> 4669</li> 4670</ul> 4671</div> 4672</div> 4673</div> 4674</div> 4675<div class="sect1"> 4676<h2 id="enable_shared_from_this">enable_shared_from_this</h2> 4677<div class="sectionbody"> 4678<div class="sect2"> 4679<h3 id="enable_shared_from_this_description">Description</h3> 4680<div class="paragraph"> 4681<p>The class template <code>enable_shared_from_this</code> is used as a base class that allows 4682a <code>shared_ptr</code> or a <code>weak_ptr</code> to the current object to be obtained from within a 4683member function.</p> 4684</div> 4685<div class="paragraph"> 4686<p><code>enable_shared_from_this<T></code> defines two member functions called <code>shared_from_this</code> 4687that return a <code>shared_ptr<T></code> and <code>shared_ptr<T const></code>, depending on constness, to 4688<code>this</code>. It also defines two member functions called <code>weak_from_this</code> that return a 4689corresponding <code>weak_ptr</code>.</p> 4690</div> 4691</div> 4692<div class="sect2"> 4693<h3 id="enable_shared_from_this_example">Example</h3> 4694<div class="listingblock"> 4695<div class="content"> 4696<pre class="highlight"><code>#include <boost/enable_shared_from_this.hpp> 4697#include <boost/shared_ptr.hpp> 4698#include <cassert> 4699 4700class Y: public boost::enable_shared_from_this<Y> 4701{ 4702public: 4703 4704 boost::shared_ptr<Y> f() 4705 { 4706 return shared_from_this(); 4707 } 4708}; 4709 4710int main() 4711{ 4712 boost::shared_ptr<Y> p(new Y); 4713 boost::shared_ptr<Y> q = p->f(); 4714 assert(p == q); 4715 assert(!(p < q || q < p)); // p and q must share ownership 4716}</code></pre> 4717</div> 4718</div> 4719</div> 4720<div class="sect2"> 4721<h3 id="enable_shared_from_this_synopsis">Synopsis</h3> 4722<div class="paragraph"> 4723<p><code>enable_shared_from_this</code> is defined in <code><boost/smart_ptr/enable_shared_from_this.hpp></code>.</p> 4724</div> 4725<div class="listingblock"> 4726<div class="content"> 4727<pre class="highlight"><code>namespace boost { 4728 4729 template<class T> class enable_shared_from_this { 4730 private: 4731 4732 // exposition only 4733 weak_ptr<T> weak_this_; 4734 4735 protected: 4736 4737 enable_shared_from_this() = default; 4738 ~enable_shared_from_this() = default; 4739 4740 enable_shared_from_this(const enable_shared_from_this&) noexcept; 4741 enable_shared_from_this& operator=(const enable_shared_from_this&) noexcept; 4742 4743 public: 4744 4745 shared_ptr<T> shared_from_this(); 4746 shared_ptr<T const> shared_from_this() const; 4747 4748 weak_ptr<T> weak_from_this() noexcept; 4749 weak_ptr<T const> weak_from_this() const noexcept; 4750 } 4751}</code></pre> 4752</div> 4753</div> 4754</div> 4755<div class="sect2"> 4756<h3 id="enable_shared_from_this_members">Members</h3> 4757<div class="listingblock"> 4758<div class="content"> 4759<pre class="highlight"><code>enable_shared_from_this(enable_shared_from_this const &) noexcept;</code></pre> 4760</div> 4761</div> 4762<div class="ulist none"> 4763<ul class="none"> 4764<li> 4765<p></p> 4766<div class="dlist"> 4767<dl> 4768<dt class="hdlist1">Effects</dt> 4769<dd> 4770<p>Default-constructs <code>weak_this_</code>.</p> 4771</dd> 4772</dl> 4773</div> 4774</li> 4775</ul> 4776</div> 4777<div class="admonitionblock note"> 4778<table> 4779<tr> 4780<td class="icon"> 4781<div class="title">Note</div> 4782</td> 4783<td class="content"> 4784<code>weak_this_</code> is <em>not</em> copied from the argument. 4785</td> 4786</tr> 4787</table> 4788</div> 4789<div class="listingblock"> 4790<div class="content"> 4791<pre class="highlight"><code>enable_shared_from_this& operator=(enable_shared_from_this const &) noexcept;</code></pre> 4792</div> 4793</div> 4794<div class="ulist none"> 4795<ul class="none"> 4796<li> 4797<p></p> 4798<div class="dlist"> 4799<dl> 4800<dt class="hdlist1">Returns</dt> 4801<dd> 4802<p><code>*this</code>.</p> 4803</dd> 4804</dl> 4805</div> 4806</li> 4807</ul> 4808</div> 4809<div class="admonitionblock note"> 4810<table> 4811<tr> 4812<td class="icon"> 4813<div class="title">Note</div> 4814</td> 4815<td class="content"> 4816<code>weak_this_</code> is unchanged. 4817</td> 4818</tr> 4819</table> 4820</div> 4821<div class="listingblock"> 4822<div class="content"> 4823<pre class="highlight"><code>template<class T> shared_ptr<T> shared_from_this();</code></pre> 4824</div> 4825</div> 4826<div class="listingblock"> 4827<div class="content"> 4828<pre class="highlight"><code>template<class T> shared_ptr<T const> shared_from_this() const;</code></pre> 4829</div> 4830</div> 4831<div class="ulist none"> 4832<ul class="none"> 4833<li> 4834<p></p> 4835<div class="dlist"> 4836<dl> 4837<dt class="hdlist1">Returns</dt> 4838<dd> 4839<p><code>shared_ptr<T>(weak_this_)</code>.</p> 4840</dd> 4841</dl> 4842</div> 4843</li> 4844</ul> 4845</div> 4846<div class="admonitionblock note"> 4847<table> 4848<tr> 4849<td class="icon"> 4850<div class="title">Note</div> 4851</td> 4852<td class="content"> 4853These members throw <code>bad_weak_ptr</code> when <code>*this</code> is not owned by a <code>shared_ptr</code>. 4854</td> 4855</tr> 4856</table> 4857</div> 4858<div class="admonitionblock note"> 4859<table> 4860<tr> 4861<td class="icon"> 4862<div class="title">Note</div> 4863</td> 4864<td class="content"> 4865<div class="paragraph"> 4866<p><code>weak_this_</code> is initialized by <code>shared_ptr</code> to a copy of itself when it’s constructed by a pointer to <code>*this</code>. 4867For example, in the following code:</p> 4868</div> 4869<div class="listingblock"> 4870<div class="content"> 4871<pre class="highlight"><code>class Y: public boost::enable_shared_from_this<Y> {}; 4872 4873int main() 4874{ 4875 boost::shared_ptr<Y> p(new Y); 4876}</code></pre> 4877</div> 4878</div> 4879<div class="paragraph"> 4880<p>the construction of <code>p</code> will automatically initialize <code>p->weak_this_</code> to <code>p</code>.</p> 4881</div> 4882</td> 4883</tr> 4884</table> 4885</div> 4886<div class="listingblock"> 4887<div class="content"> 4888<pre class="highlight"><code>template<class T> weak_ptr<T> weak_from_this() noexcept;</code></pre> 4889</div> 4890</div> 4891<div class="listingblock"> 4892<div class="content"> 4893<pre class="highlight"><code>template<class T> weak_ptr<T const> weak_from_this() const noexcept;</code></pre> 4894</div> 4895</div> 4896<div class="ulist none"> 4897<ul class="none"> 4898<li> 4899<p></p> 4900<div class="dlist"> 4901<dl> 4902<dt class="hdlist1">Returns</dt> 4903<dd> 4904<p><code>weak_this_</code>.</p> 4905</dd> 4906</dl> 4907</div> 4908</li> 4909</ul> 4910</div> 4911<div class="admonitionblock note"> 4912<table> 4913<tr> 4914<td class="icon"> 4915<div class="title">Note</div> 4916</td> 4917<td class="content"> 4918Unlike <code>shared_from_this()</code>, <code>weak_from_this()</code> is valid in a destructor 4919 and returns a <code>weak_ptr</code> that is <code>expired()</code> but still shares ownership 4920 with other <code>weak_ptr</code> instances (if any) that refer to the object. 4921</td> 4922</tr> 4923</table> 4924</div> 4925</div> 4926</div> 4927</div> 4928<div class="sect1"> 4929<h2 id="enable_shared_from">enable_shared_from</h2> 4930<div class="sectionbody"> 4931<div class="sect2"> 4932<h3 id="enable_shared_from_description">Description</h3> 4933<div class="paragraph"> 4934<p><code>enable_shared_from</code> is used as a base class that allows a <code>shared_ptr</code> or a 4935<code>weak_ptr</code> to be obtained given a raw pointer to the object, by using the 4936functions <code>shared_from</code> and <code>weak_from</code>.</p> 4937</div> 4938<div class="paragraph"> 4939<p><code>enable_shared_from</code> differs from <code>enable_shared_from_this<T></code> by the fact 4940that it’s not a template, and is its recommended replacement for new code.</p> 4941</div> 4942</div> 4943<div class="sect2"> 4944<h3 id="enable_shared_from_example">Example</h3> 4945<div class="listingblock"> 4946<div class="content"> 4947<pre class="highlight"><code>#include <boost/smart_ptr/enable_shared_from.hpp> 4948#include <boost/shared_ptr.hpp> 4949#include <cassert> 4950 4951class Y: public boost::enable_shared_from 4952{ 4953public: 4954 4955 boost::shared_ptr<Y> f() 4956 { 4957 return boost::shared_from( this ); 4958 } 4959}; 4960 4961int main() 4962{ 4963 boost::shared_ptr<Y> p(new Y); 4964 boost::shared_ptr<Y> q = p->f(); 4965 assert(p == q); 4966 assert(!(p < q || q < p)); // p and q must share ownership 4967}</code></pre> 4968</div> 4969</div> 4970</div> 4971<div class="sect2"> 4972<h3 id="enable_shared_from_synopsis">Synopsis</h3> 4973<div class="paragraph"> 4974<p><code>enable_shared_from</code> is defined in <code><boost/smart_ptr/enable_shared_from.hpp></code>.</p> 4975</div> 4976<div class="listingblock"> 4977<div class="content"> 4978<pre class="highlight"><code>namespace boost { 4979 4980 class enable_shared_from: public enable_shared_from_this<enable_shared_from> 4981 { 4982 }; 4983 4984 template<class T> shared_ptr<T> shared_from( T * p ); 4985 template<class T> weak_ptr<T> weak_from( T * p ) noexcept; 4986}</code></pre> 4987</div> 4988</div> 4989</div> 4990<div class="sect2"> 4991<h3 id="enable_shared_from_functions">Functions</h3> 4992<div class="listingblock"> 4993<div class="content"> 4994<pre class="highlight"><code>template<class T> shared_ptr<T> shared_from( T * p );</code></pre> 4995</div> 4996</div> 4997<div class="ulist none"> 4998<ul class="none"> 4999<li> 5000<p></p> 5001<div class="dlist"> 5002<dl> 5003<dt class="hdlist1">Returns</dt> 5004<dd> 5005<p><code>shared_ptr<T>( p->enable_shared_from::shared_from_this(), p )</code>.</p> 5006</dd> 5007</dl> 5008</div> 5009</li> 5010</ul> 5011</div> 5012<div class="admonitionblock note"> 5013<table> 5014<tr> 5015<td class="icon"> 5016<div class="title">Note</div> 5017</td> 5018<td class="content"> 5019Throws <code>bad_weak_ptr</code> when <code>p</code> is not owned by a <code>shared_ptr</code>. 5020</td> 5021</tr> 5022</table> 5023</div> 5024<div class="listingblock"> 5025<div class="content"> 5026<pre class="highlight"><code>template<class T> weak_ptr<T> weak_from( T * p ) noexcept;</code></pre> 5027</div> 5028</div> 5029<div class="ulist none"> 5030<ul class="none"> 5031<li> 5032<p></p> 5033<div class="dlist"> 5034<dl> 5035<dt class="hdlist1">Returns</dt> 5036<dd> 5037<p><code>weak_ptr<T>( p->enable_shared_from::weak_from_this(), p )</code>.</p> 5038</dd> 5039</dl> 5040</div> 5041</li> 5042</ul> 5043</div> 5044<div class="admonitionblock note"> 5045<table> 5046<tr> 5047<td class="icon"> 5048<div class="title">Note</div> 5049</td> 5050<td class="content"> 5051Unlike <code>shared_from(this)</code>, <code>weak_from(this)</code> is valid in a destructor 5052 and returns a <code>weak_ptr</code> that is <code>expired()</code> but still shares ownership 5053 with other <code>weak_ptr</code> instances (if any) that refer to the object. 5054</td> 5055</tr> 5056</table> 5057</div> 5058</div> 5059</div> 5060</div> 5061<div class="sect1"> 5062<h2 id="make_unique">make_unique: Creating unique_ptr</h2> 5063<div class="sectionbody"> 5064<div class="sect2"> 5065<h3 id="make_unique_description">Description</h3> 5066<div class="paragraph"> 5067<p>The <code>make_unique</code> function templates provide convenient and safe ways to 5068create <code>std::unique_ptr</code> objects.</p> 5069</div> 5070</div> 5071<div class="sect2"> 5072<h3 id="make_unique_rationale">Rationale</h3> 5073<div class="paragraph"> 5074<p>The C++11 standard introduced <code>std::unique_ptr</code> but did not provide any 5075<code>make_unique</code> utility like <code>std::make_shared</code> that provided the same 5076exception safety and facility to avoid writing <code>new</code> expressions. Before it 5077was implemented by some standard library vendors (and prior to the C++14 5078standard introducing <code>std::make_unique</code>), this library provided it due to 5079requests from users.</p> 5080</div> 5081<div class="paragraph"> 5082<p>This library also provides additional overloads of <code>make_unique</code> for 5083default-initialization, when users do not need or want to incur the expense 5084of value-initialization. The C++ standard does not yet provide this 5085feature with <code>std::make_unique</code>.</p> 5086</div> 5087</div> 5088<div class="sect2"> 5089<h3 id="make_unique_synopsis">Synopsis</h3> 5090<div class="paragraph"> 5091<p><code>make_unique</code> is defined in <code><boost/smart_ptr/make_unique.hpp></code>.</p> 5092</div> 5093<div class="listingblock"> 5094<div class="content"> 5095<pre class="highlight"><code>namespace boost { 5096 <code>// T is not an array</code> 5097 template<class T, class... Args> 5098 std::unique_ptr<T> make_unique(Args&&... args); 5099 5100 <code>// T is not an array</code> 5101 template<class T> 5102 std::unique_ptr<T> make_unique(type_identity_t<T>&& v); 5103 5104 <code>// T is an array of unknown bounds</code> 5105 template<class T> 5106 std::unique_ptr<T> make_unique(std::size_t n); 5107 5108 <code>// T is not an array</code> 5109 template<class T> 5110 std::unique_ptr<T> make_unique_noinit(); 5111 5112 <code>// T is an array of unknown bounds</code> 5113 template<class T> 5114 std::unique_ptr<T> make_unique_noinit(std::size_t n); 5115}</code></pre> 5116</div> 5117</div> 5118</div> 5119<div class="sect2"> 5120<h3 id="make_unique_free_functions">Free Functions</h3> 5121<div class="listingblock"> 5122<div class="content"> 5123<pre class="highlight"><code>template<class T, class... Args> 5124 std::unique_ptr<T> make_unique(Args&&... args);</code></pre> 5125</div> 5126</div> 5127<div class="ulist none"> 5128<ul class="none"> 5129<li> 5130<p></p> 5131<div class="dlist"> 5132<dl> 5133<dt class="hdlist1">Constraints</dt> 5134<dd> 5135<p><code>T</code> is not an array.</p> 5136</dd> 5137<dt class="hdlist1">Returns</dt> 5138<dd> 5139<p><code>std::unique_ptr<T>(new T(std::forward<Args>(args)...)</code>.</p> 5140</dd> 5141<dt class="hdlist1">Example</dt> 5142<dd> 5143<p><code>auto p = make_unique<int>();</code></p> 5144</dd> 5145</dl> 5146</div> 5147</li> 5148</ul> 5149</div> 5150<div class="listingblock"> 5151<div class="content"> 5152<pre class="highlight"><code>template<class T> 5153 std::unique_ptr<T> make_unique(type_identity_t<T>&& v);</code></pre> 5154</div> 5155</div> 5156<div class="ulist none"> 5157<ul class="none"> 5158<li> 5159<p></p> 5160<div class="dlist"> 5161<dl> 5162<dt class="hdlist1">Constraints</dt> 5163<dd> 5164<p><code>T</code> is not an array.</p> 5165</dd> 5166<dt class="hdlist1">Returns</dt> 5167<dd> 5168<p><code>std::unique_ptr<T>(new T(std::move(v))</code>.</p> 5169</dd> 5170<dt class="hdlist1">Example</dt> 5171<dd> 5172<p><code>auto p = make_unique<std::vector<int> >({1, 2});</code></p> 5173</dd> 5174</dl> 5175</div> 5176</li> 5177</ul> 5178</div> 5179<div class="listingblock"> 5180<div class="content"> 5181<pre class="highlight"><code>template<class T> 5182 std::unique_ptr<T> make_unique(std::size_t n);</code></pre> 5183</div> 5184</div> 5185<div class="ulist none"> 5186<ul class="none"> 5187<li> 5188<p></p> 5189<div class="dlist"> 5190<dl> 5191<dt class="hdlist1">Constraints</dt> 5192<dd> 5193<p><code>T</code> is an array of unknown bounds.</p> 5194</dd> 5195<dt class="hdlist1">Returns</dt> 5196<dd> 5197<p><code>std::unique_ptr<T>(new remove_extent_t<T>[n]())</code>.</p> 5198</dd> 5199<dt class="hdlist1">Example</dt> 5200<dd> 5201<p><code>auto p = make_unique<double[]>(1024);</code></p> 5202</dd> 5203</dl> 5204</div> 5205</li> 5206</ul> 5207</div> 5208<div class="listingblock"> 5209<div class="content"> 5210<pre class="highlight"><code>template<class T> 5211 std::unique_ptr<T> make_unique_noinit();</code></pre> 5212</div> 5213</div> 5214<div class="ulist none"> 5215<ul class="none"> 5216<li> 5217<p></p> 5218<div class="dlist"> 5219<dl> 5220<dt class="hdlist1">Constraints</dt> 5221<dd> 5222<p><code>T</code> is not an array.</p> 5223</dd> 5224<dt class="hdlist1">Returns</dt> 5225<dd> 5226<p><code>std::unique_ptr<T>(new T)</code>.</p> 5227</dd> 5228<dt class="hdlist1">Example</dt> 5229<dd> 5230<p><code>auto p = make_unique_noinit<std::array<double, 1024> >();</code></p> 5231</dd> 5232</dl> 5233</div> 5234</li> 5235</ul> 5236</div> 5237<div class="listingblock"> 5238<div class="content"> 5239<pre class="highlight"><code>template<class T> 5240 std::unique_ptr<T> make_unique_noinit(std::size_t n);</code></pre> 5241</div> 5242</div> 5243<div class="ulist none"> 5244<ul class="none"> 5245<li> 5246<p></p> 5247<div class="dlist"> 5248<dl> 5249<dt class="hdlist1">Constraints</dt> 5250<dd> 5251<p><code>T</code> is an array of unknown bounds.</p> 5252</dd> 5253<dt class="hdlist1">Returns</dt> 5254<dd> 5255<p><code>std::unique_ptr<T>(new remove_extent_t<T>[n])</code>.</p> 5256</dd> 5257<dt class="hdlist1">Example</dt> 5258<dd> 5259<p><code>auto p = make_unique_noinit<double[]>(1024);</code></p> 5260</dd> 5261</dl> 5262</div> 5263</li> 5264</ul> 5265</div> 5266</div> 5267</div> 5268</div> 5269<div class="sect1"> 5270<h2 id="allocate_unique">allocate_unique: Creating unique_ptr</h2> 5271<div class="sectionbody"> 5272<div class="sect2"> 5273<h3 id="allocate_unique_description">Description</h3> 5274<div class="paragraph"> 5275<p>The <code>allocate_unique</code> family of function templates provide convenient and safe 5276ways to obtain a <code>std::unique_ptr</code> that manages a new object created using an 5277allocator.</p> 5278</div> 5279</div> 5280<div class="sect2"> 5281<h3 id="allocate_unique_rationale">Rationale</h3> 5282<div class="paragraph"> 5283<p>The C++14 standard introduced <code>std::make_unique</code> which used operator <code>new</code> to 5284create new objects. However, there is no convenient facility in the standard 5285library to use an allocator for the creation of the objects managed by 5286<code>std::unique_ptr</code>. Users writing allocator aware code have often requested an 5287<code>allocate_unique</code> factory function. This function is to <code>std::unique_ptr</code> what 5288<code>std::allocate_shared</code> is to <code>std::shared_ptr</code>.</p> 5289</div> 5290</div> 5291<div class="sect2"> 5292<h3 id="allocate_unique_synopsis">Synopsis</h3> 5293<div class="paragraph"> 5294<p><code>allocate_unique</code> is defined in <code><boost/smart_ptr/allocate_unique.hpp></code>.</p> 5295</div> 5296<div class="listingblock"> 5297<div class="content"> 5298<pre class="highlight"><code>namespace boost { 5299 template<class T, class A> 5300 class alloc_deleter; 5301 5302 template<class T, class A> 5303 using alloc_noinit_deleter = alloc_deleter<T, noinit_adaptor<A>>; 5304 5305 <code>// T is not an array</code> 5306 template<class T, class A, class... Args> 5307 std::unique_ptr<T, alloc_deleter<T, A>> 5308 allocate_unique(const A& a, Args&&... args); 5309 5310 <code>// T is not an array</code> 5311 template<class T, class A> 5312 std::unique_ptr<T, alloc_deleter<T, A>> 5313 allocate_unique(const A& a, type_identity_t<T>&& v); 5314 5315 <code>// T is an array of unknown bounds</code> 5316 template<class T, class A> 5317 std::unique_ptr<T, alloc_deleter<T, A>> 5318 allocate_unique(const A& a, std::size_t n); 5319 5320 <code>// T is an array of known bounds</code> 5321 template<class T, class A> 5322 std::unique_ptr<remove_extent_t<T>[], alloc_deleter<T, A>> 5323 allocate_unique(const A& a); 5324 5325 <code>// T is an array of unknown bounds</code> 5326 template<class T, class A> 5327 std::unique_ptr<T, alloc_deleter<T, A>> 5328 allocate_unique(const A& a, std::size_t n, const remove_extent_t<T>& v); 5329 5330 <code>// T is an array of known bounds</code> 5331 template<class T, class A> 5332 std::unique_ptr<remove_extent_t<T>[], alloc_deleter<T, A>> 5333 allocate_unique(const A& a, const remove_extent_t<T>& v); 5334 5335 <code>// T is not an array</code> 5336 template<class T, class A> 5337 std::unique_ptr<T, alloc_noinit_deleter<T, A>> 5338 allocate_unique_noinit(const A& a); 5339 5340 <code>// T is an array of unknown bounds</code> 5341 template<class T, class A> 5342 std::unique_ptr<T, alloc_noinit_deleter<T, A>> 5343 allocate_unique_noinit(const A& a, std::size_t n); 5344 5345 <code>// T is an array of known bounds</code> 5346 template<class T, class A> 5347 std::unique_ptr<remove_extent_t<T>[], alloc_noinit_deleter<T, A>> 5348 allocate_unique_noinit(const A& a); 5349}</code></pre> 5350</div> 5351</div> 5352</div> 5353<div class="sect2"> 5354<h3 id="allocate_unique_common_requirements">Common Requirements</h3> 5355<div class="paragraph"> 5356<p>The common requirements that apply to all <code>allocate_unique</code> and 5357<code>allocate_unique_noinit</code> overloads, unless specified otherwise, are described 5358below.</p> 5359</div> 5360<div class="dlist"> 5361<dl> 5362<dt class="hdlist1">Requires</dt> 5363<dd> 5364<p><code>A</code> shall be an <em>allocator</em>. The copy constructor and destructor 5365of <code>A</code> shall not throw exceptions.</p> 5366</dd> 5367<dt class="hdlist1">Effects</dt> 5368<dd> 5369<p>Allocates memory for an object of type <code>T</code> or <code>n</code> objects of <code>U</code> 5370(if <code>T</code> is an array type of the form <code>U[]</code> and <code>n</code> is determined by 5371arguments, as specified by the concrete overload). The object is initialized 5372from arguments as specified by the concrete overload. Uses a rebound copy of 5373<code>a</code> (for an unspecified <code>value_type</code>) to allocate memory. If an exception is 5374thrown, the functions have no effect.</p> 5375</dd> 5376<dt class="hdlist1">Returns</dt> 5377<dd> 5378<p>A <code>std::unique_ptr</code> instance that stores and owns the address of the 5379newly constructed object.</p> 5380</dd> 5381<dt class="hdlist1">Postconditions</dt> 5382<dd> 5383<p><code>r.get() != 0</code>, where <code>r</code> is the return value.</p> 5384</dd> 5385<dt class="hdlist1">Throws</dt> 5386<dd> 5387<p>An exception thrown from <code>A::allocate</code>, or from the initialization of 5388the object.</p> 5389</dd> 5390<dt class="hdlist1">Remarks</dt> 5391<dd> 5392<div class="ulist"> 5393<ul> 5394<li> 5395<p>When an object of an array type is specified to be initialized to a value of 5396the same type <code>v</code>, this shall be interpreted to mean that each array element 5397of the object is initialized to the corresponding element from <code>v</code>.</p> 5398</li> 5399<li> 5400<p>When an object of an array type is specified to be value-initialized, this 5401shall be interpreted to mean that each array element of the object is 5402value-initialized.</p> 5403</li> 5404<li> 5405<p>When a (sub)object of non-array type <code>U</code> is specified to be initialized to a 5406value <code>v</code>, or constructed from <code>args...</code>, <code>allocate_unique</code> shall perform this 5407initialization via the expression 5408<code>std::allocator_traits<A2>::construct(a2, p, expr)</code> (where <code><em>expr</em></code> is <code>v</code> or 5409<code>std::forward<Args>(args)...)</code> respectively), <code>p</code> points to storage suitable 5410to hold an object of type <code>U</code>, and <code>a2</code> of type <code>A2</code> is a potentially rebound 5411copy of <code>a</code>.</p> 5412</li> 5413<li> 5414<p>When a (sub)object of non-array type <code>U</code> is specified to be 5415default-initialized, <code>allocate_unique_noinit</code> shall perform this initialization 5416via the expression <code>::new(p) U</code>, where <code>p</code> has type <code>void*</code> and points to 5417storage suitable to hold an object of type <code>U</code>.</p> 5418</li> 5419<li> 5420<p>When a (sub)object of non-array type <code>U</code> is specified to be 5421value-initialized, <code>allocate_unique</code> shall perform this initialization via the 5422expression <code>std::allocator_traits<A2>::construct(a2, p)</code>, where <code>p</code> points to 5423storage suitable to hold an object of type <code>U</code> and <code>a2</code> of type <code>A2</code> is a 5424potentially rebound copy of <code>a</code>.</p> 5425</li> 5426<li> 5427<p>Array elements are initialized in ascending order of their addresses.</p> 5428</li> 5429<li> 5430<p>When the lifetime of the object managed by the return value ends, or when the 5431initialization of an array element throws an exception, the initialized 5432elements should be destroyed in the reverse order of their construction.</p> 5433</li> 5434</ul> 5435</div> 5436</dd> 5437</dl> 5438</div> 5439</div> 5440<div class="sect2"> 5441<h3 id="allocate_unique_free_functions">Free Functions</h3> 5442<div class="listingblock"> 5443<div class="content"> 5444<pre class="highlight"><code>template<class T, class A, class... Args> 5445 std::unique_ptr<T, alloc_deleter<T, A>> 5446 allocate_unique(const A& a, Args&&... args);</code></pre> 5447</div> 5448</div> 5449<div class="ulist none"> 5450<ul class="none"> 5451<li> 5452<p></p> 5453<div class="dlist"> 5454<dl> 5455<dt class="hdlist1">Constraints</dt> 5456<dd> 5457<p><code>T</code> is not an array.</p> 5458</dd> 5459<dt class="hdlist1">Returns</dt> 5460<dd> 5461<p>A <code>std::unique_ptr</code> to an object of type <code>T</code>, constructed from 5462<code>args...</code>.</p> 5463</dd> 5464<dt class="hdlist1">Examples</dt> 5465</dl> 5466</div> 5467</li> 5468<li> 5469<p><code>auto p = allocate_unique<int>(a);</code></p> 5470</li> 5471<li> 5472<p><code>auto p = allocate_unique<std::vector<int>>(a, 16, 1);</code></p> 5473</li> 5474</ul> 5475</div> 5476<div class="listingblock"> 5477<div class="content"> 5478<pre class="highlight"><code>template<class T, class A> 5479 std::unique_ptr<T, alloc_deleter<T, A>> 5480 allocate_unique(const A& a, type_identity_t<T>&& v);</code></pre> 5481</div> 5482</div> 5483<div class="ulist none"> 5484<ul class="none"> 5485<li> 5486<p></p> 5487<div class="dlist"> 5488<dl> 5489<dt class="hdlist1">Constraints</dt> 5490<dd> 5491<p><code>T</code> is not an array.</p> 5492</dd> 5493<dt class="hdlist1">Returns</dt> 5494<dd> 5495<p>A <code>std::unique_ptr</code> to an object of type <code>T</code>, constructed from <code>v</code>.</p> 5496</dd> 5497<dt class="hdlist1">Example</dt> 5498<dd> 5499<p><code>auto p = allocate_unique<std::vector<int>>(a, {1, 2});</code></p> 5500</dd> 5501</dl> 5502</div> 5503</li> 5504</ul> 5505</div> 5506<div class="listingblock"> 5507<div class="content"> 5508<pre class="highlight"><code>template<class T, class A> 5509 std::unique_ptr<T, alloc_deleter<T, A>> 5510 allocate_unique(const A& a, std::size_t n);</code></pre> 5511</div> 5512</div> 5513<div class="ulist none"> 5514<ul class="none"> 5515<li> 5516<p></p> 5517<div class="dlist"> 5518<dl> 5519<dt class="hdlist1">Constraints</dt> 5520<dd> 5521<p><code>T</code> is an array of unknown bounds.</p> 5522</dd> 5523<dt class="hdlist1">Returns</dt> 5524<dd> 5525<p>A <code>std::unique_ptr</code> to a sequence of <code>n</code> value-initialized objects of 5526type <code>remove_extent_t<T></code>.</p> 5527</dd> 5528<dt class="hdlist1">Examples</dt> 5529</dl> 5530</div> 5531</li> 5532<li> 5533<p><code>auto p = allocate_unique<double[]>(a, 1024);</code></p> 5534</li> 5535<li> 5536<p><code>auto p = allocate_unique<double[][2][2]>(a, 6);</code></p> 5537</li> 5538</ul> 5539</div> 5540<div class="listingblock"> 5541<div class="content"> 5542<pre class="highlight"><code>template<class T, class A> 5543 std::unique_ptr<remove_extent_t<T>[], alloc_deleter<T, A>> 5544 allocate_unique(const A& a);</code></pre> 5545</div> 5546</div> 5547<div class="ulist none"> 5548<ul class="none"> 5549<li> 5550<p></p> 5551<div class="dlist"> 5552<dl> 5553<dt class="hdlist1">Constraints</dt> 5554<dd> 5555<p><code>T</code> is an array of known bounds.</p> 5556</dd> 5557<dt class="hdlist1">Returns</dt> 5558<dd> 5559<p>A <code>std::unique_ptr</code> to a sequence of <code>extent_v<T></code> value-initialized 5560objects of type <code>remove_extent_t<T></code>.</p> 5561</dd> 5562<dt class="hdlist1">Examples</dt> 5563</dl> 5564</div> 5565</li> 5566<li> 5567<p><code>auto p = allocate_unique<double[1024]>(a);</code></p> 5568</li> 5569<li> 5570<p><code>auto p = allocate_unique<double[6][2][2]>(a);</code></p> 5571</li> 5572</ul> 5573</div> 5574<div class="listingblock"> 5575<div class="content"> 5576<pre class="highlight"><code>template<class T, class A> 5577 std::unique_ptr<T, alloc_deleter<T, A>> 5578 allocate_unique(const A& a, std::size_t n, const remove_extent_t<T>& v);</code></pre> 5579</div> 5580</div> 5581<div class="ulist none"> 5582<ul class="none"> 5583<li> 5584<p></p> 5585<div class="dlist"> 5586<dl> 5587<dt class="hdlist1">Constraints</dt> 5588<dd> 5589<p><code>T</code> is an array of unknown bounds.</p> 5590</dd> 5591<dt class="hdlist1">Returns</dt> 5592<dd> 5593<p>A <code>std::unique_ptr</code> to a sequence of <code>n</code> objects of type 5594<code>remove_extent_t<T></code>, each initialized to <code>v</code>.</p> 5595</dd> 5596<dt class="hdlist1">Examples</dt> 5597</dl> 5598</div> 5599</li> 5600<li> 5601<p><code>auto p = allocate_unique<double[]>(a, 1024, 1.0);</code></p> 5602</li> 5603<li> 5604<p><code>auto p = allocate_unique<double[][2]>(a, 6, {1.0, 0.0});</code></p> 5605</li> 5606<li> 5607<p><code>auto p = allocate_unique<std::vector<int>[]>(a, 4, {1, 2});</code></p> 5608</li> 5609</ul> 5610</div> 5611<div class="listingblock"> 5612<div class="content"> 5613<pre class="highlight"><code>template<class T, class A> 5614 std::unique_ptr<remove_extent_t<T>[], alloc_deleter<T, A>> 5615 allocate_unique(const A& a, const remove_extent_t<T>& v);</code></pre> 5616</div> 5617</div> 5618<div class="ulist none"> 5619<ul class="none"> 5620<li> 5621<p></p> 5622<div class="dlist"> 5623<dl> 5624<dt class="hdlist1">Constraints</dt> 5625<dd> 5626<p><code>T</code> is an array of known bounds.</p> 5627</dd> 5628<dt class="hdlist1">Returns</dt> 5629<dd> 5630<p>A <code>std::unique_ptr</code> to a sequence of <code>extent_v<T></code> objects of type 5631<code>remove_extent_t<T></code>, each initialized to <code>v</code>.</p> 5632</dd> 5633<dt class="hdlist1">Examples</dt> 5634</dl> 5635</div> 5636</li> 5637<li> 5638<p><code>auto p = allocate_unique<double[1024]>(a, 1.0);</code></p> 5639</li> 5640<li> 5641<p><code>auto p = allocate_unique<double[6][2]>(a, {1.0, 0.0});</code></p> 5642</li> 5643<li> 5644<p><code>auto p = allocate_unique<std::vector<int>[4]>(a, {1, 2});</code></p> 5645</li> 5646</ul> 5647</div> 5648<div class="listingblock"> 5649<div class="content"> 5650<pre class="highlight"><code>template<class T, class A> 5651 std::unique_ptr<T, alloc_noinit_deleter<T, A>> 5652 allocate_unique_noinit(const A& a);</code></pre> 5653</div> 5654</div> 5655<div class="ulist none"> 5656<ul class="none"> 5657<li> 5658<p></p> 5659<div class="dlist"> 5660<dl> 5661<dt class="hdlist1">Constraints</dt> 5662<dd> 5663<p><code>T</code> is not an array.</p> 5664</dd> 5665<dt class="hdlist1">Returns</dt> 5666<dd> 5667<p>A <code>std::unique_ptr</code> to a default-initialized object of type <code>T</code>.</p> 5668</dd> 5669<dt class="hdlist1">Example</dt> 5670<dd> 5671<p><code>auto p = allocate_unique_noinit<double>(a);</code></p> 5672</dd> 5673</dl> 5674</div> 5675</li> 5676</ul> 5677</div> 5678<div class="listingblock"> 5679<div class="content"> 5680<pre class="highlight"><code>template<class T, class A> 5681 std::unique_ptr<T, alloc_noinit_deleter<T, A>> 5682 allocate_unique_noinit(const A& a, std::size_t n);</code></pre> 5683</div> 5684</div> 5685<div class="ulist none"> 5686<ul class="none"> 5687<li> 5688<p></p> 5689<div class="dlist"> 5690<dl> 5691<dt class="hdlist1">Constraints</dt> 5692<dd> 5693<p><code>T</code> is an array of unknown bounds.</p> 5694</dd> 5695<dt class="hdlist1">Returns</dt> 5696<dd> 5697<p>A <code>std::unique_ptr</code> to a sequence of <code>n</code> default-initialized objects 5698of type <code>remove_extent_t<T></code>.</p> 5699</dd> 5700<dt class="hdlist1">Example</dt> 5701<dd> 5702<p><code>auto p = allocate_unique_noinit<double[]>(a, 1024);</code></p> 5703</dd> 5704</dl> 5705</div> 5706</li> 5707</ul> 5708</div> 5709<div class="listingblock"> 5710<div class="content"> 5711<pre class="highlight"><code>template<class T, class A> 5712 std::unique_ptr<remove_extent_t<T>, alloc_noinit_deleter<T, A>> 5713 allocate_unique_noinit(const A& a);</code></pre> 5714</div> 5715</div> 5716<div class="ulist none"> 5717<ul class="none"> 5718<li> 5719<p></p> 5720<div class="dlist"> 5721<dl> 5722<dt class="hdlist1">Constraints</dt> 5723<dd> 5724<p><code>T</code> is an array of known bounds.</p> 5725</dd> 5726<dt class="hdlist1">Returns</dt> 5727<dd> 5728<p>A <code>std::unique_ptr</code> to a sequence of <code>extent_v<T></code> 5729default-initialized objects of type <code>remove_extent_t<T></code>.</p> 5730</dd> 5731<dt class="hdlist1">Example</dt> 5732<dd> 5733<p><code>auto p = allocate_unique_noinit<double[1024]>(a);</code></p> 5734</dd> 5735</dl> 5736</div> 5737</li> 5738</ul> 5739</div> 5740</div> 5741<div class="sect2"> 5742<h3 id="allocate_unique_deleter">Deleter</h3> 5743<div class="paragraph"> 5744<p>Class template <code>alloc_deleter</code> is the deleter used by the <code>allocate_unique</code> 5745functions.</p> 5746</div> 5747<div class="sect3"> 5748<h4 id="allocate_unique_synopsis_2">Synopsis</h4> 5749<div class="listingblock"> 5750<div class="content"> 5751<pre class="highlight"><code>template<class T, class A> 5752class alloc_deleter { 5753public: 5754 using pointer = <code>unspecified</code>; 5755 5756 explicit alloc_deleter(const A& a) noexcept; 5757 5758 void operator()(pointer p); 5759};</code></pre> 5760</div> 5761</div> 5762</div> 5763<div class="sect3"> 5764<h4 id="allocate_unique_members">Members</h4> 5765<div class="listingblock"> 5766<div class="content"> 5767<pre class="highlight"><code>using pointer = <code>unspecified</code>;</code></pre> 5768</div> 5769</div> 5770<div class="ulist none"> 5771<ul class="none"> 5772<li> 5773<p></p> 5774<div class="paragraph"> 5775<p>A type that satisfies <em>NullablePointer</em>.</p> 5776</div> 5777</li> 5778</ul> 5779</div> 5780<div class="listingblock"> 5781<div class="content"> 5782<pre class="highlight"><code>explicit alloc_deleter(const A& a) noexcept;</code></pre> 5783</div> 5784</div> 5785<div class="ulist none"> 5786<ul class="none"> 5787<li> 5788<p></p> 5789<div class="dlist"> 5790<dl> 5791<dt class="hdlist1">Effects</dt> 5792<dd> 5793<p>Initializes the stored allocator from <code>a</code>.</p> 5794</dd> 5795</dl> 5796</div> 5797</li> 5798</ul> 5799</div> 5800<div class="listingblock"> 5801<div class="content"> 5802<pre class="highlight"><code>void operator()(pointer p);</code></pre> 5803</div> 5804</div> 5805<div class="ulist none"> 5806<ul class="none"> 5807<li> 5808<p></p> 5809<div class="dlist"> 5810<dl> 5811<dt class="hdlist1">Effects</dt> 5812<dd> 5813<p>Destroys the objects and deallocates the storage referenced by <code>p</code>, 5814using the stored allocator.</p> 5815</dd> 5816</dl> 5817</div> 5818</li> 5819</ul> 5820</div> 5821</div> 5822</div> 5823</div> 5824</div> 5825<div class="sect1"> 5826<h2 id="intrusive_ptr">intrusive_ptr: Managing Objects with Embedded Counts</h2> 5827<div class="sectionbody"> 5828<div class="sect2"> 5829<h3 id="intrusive_ptr_description">Description</h3> 5830<div class="paragraph"> 5831<p>The <code>intrusive_ptr</code> class template stores a pointer to an object with an embedded reference count. 5832Every new <code>intrusive_ptr</code> instance increments the reference count by using an unqualified call to the 5833function <code>intrusive_ptr_add_ref</code>, passing it the pointer as an argument. Similarly, when an <code>intrusive_ptr</code> 5834is destroyed, it calls <code>intrusive_ptr_release</code>; this function is responsible for destroying the object when 5835its reference count drops to zero. The user is expected to provide suitable definitions of these two functions. 5836On compilers that support argument-dependent lookup, <code>intrusive_ptr_add_ref</code> and <code>intrusive_ptr_release</code> should 5837be defined in the namespace that corresponds to their parameter; otherwise, the definitions need to go in namespace 5838<code>boost</code>. The library provides a helper base class template <code><a href="#intrusive_ref_counter">intrusive_ref_counter</a></code> which 5839may help adding support for <code>intrusive_ptr</code> to user types.</p> 5840</div> 5841<div class="paragraph"> 5842<p>The class template is parameterized on <code>T</code>, the type of the object pointed to. <code>intrusive_ptr<T></code> can be implicitly 5843converted to <code>intrusive_ptr<U></code> whenever <code>T*</code> can be implicitly converted to <code>U*</code>.</p> 5844</div> 5845<div class="paragraph"> 5846<p>The main reasons to use <code>intrusive_ptr</code> are:</p> 5847</div> 5848<div class="ulist"> 5849<ul> 5850<li> 5851<p>Some existing frameworks or OSes provide objects with embedded reference counts;</p> 5852</li> 5853<li> 5854<p>The memory footprint of <code>intrusive_ptr</code> is the same as the corresponding raw pointer;</p> 5855</li> 5856<li> 5857<p><code>intrusive_ptr<T></code> can be constructed from an arbitrary raw pointer of type <code>T*</code>.</p> 5858</li> 5859</ul> 5860</div> 5861<div class="paragraph"> 5862<p>As a general rule, if it isn’t obvious whether <code>intrusive_ptr</code> better fits your needs than <code>shared_ptr</code>, try a <code>shared_ptr</code>-based design first.</p> 5863</div> 5864</div> 5865<div class="sect2"> 5866<h3 id="intrusive_ptr_synopsis">Synopsis</h3> 5867<div class="paragraph"> 5868<p><code>intrusive_ptr</code> is defined in <code><boost/smart_ptr/intrusive_ptr.hpp></code>.</p> 5869</div> 5870<div class="listingblock"> 5871<div class="content"> 5872<pre class="highlight"><code>namespace boost { 5873 5874 template<class T> class intrusive_ptr { 5875 public: 5876 5877 typedef T element_type; 5878 5879 intrusive_ptr() noexcept; 5880 intrusive_ptr(T * p, bool add_ref = true); 5881 5882 intrusive_ptr(intrusive_ptr const & r); 5883 template<class Y> intrusive_ptr(intrusive_ptr<Y> const & r); 5884 5885 intrusive_ptr(intrusive_ptr && r); 5886 template<class Y> intrusive_ptr(intrusive_ptr<Y> && r); 5887 5888 ~intrusive_ptr(); 5889 5890 intrusive_ptr & operator=(intrusive_ptr const & r); 5891 template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> const & r); 5892 intrusive_ptr & operator=(T * r); 5893 5894 intrusive_ptr & operator=(intrusive_ptr && r); 5895 template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> && r); 5896 5897 void reset(); 5898 void reset(T * r); 5899 void reset(T * r, bool add_ref); 5900 5901 T & operator*() const noexcept; 5902 T * operator->() const noexcept; 5903 T * get() const noexcept; 5904 T * detach() noexcept; 5905 5906 explicit operator bool () const noexcept; 5907 5908 void swap(intrusive_ptr & b) noexcept; 5909 }; 5910 5911 template<class T, class U> 5912 bool operator==(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b) noexcept; 5913 5914 template<class T, class U> 5915 bool operator!=(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b) noexcept; 5916 5917 template<class T, class U> 5918 bool operator==(intrusive_ptr<T> const & a, U * b) noexcept; 5919 5920 template<class T, class U> 5921 bool operator!=(intrusive_ptr<T> const & a, U * b) noexcept; 5922 5923 template<class T, class U> 5924 bool operator==(T * a, intrusive_ptr<U> const & b) noexcept; 5925 5926 template<class T, class U> 5927 bool operator!=(T * a, intrusive_ptr<U> const & b) noexcept; 5928 5929 template<class T> 5930 bool operator<(intrusive_ptr<T> const & a, intrusive_ptr<T> const & b) noexcept; 5931 5932 template<class T> void swap(intrusive_ptr<T> & a, intrusive_ptr<T> & b) noexcept; 5933 5934 template<class T> T * get_pointer(intrusive_ptr<T> const & p) noexcept; 5935 5936 template<class T, class U> 5937 intrusive_ptr<T> static_pointer_cast(intrusive_ptr<U> const & r) noexcept; 5938 5939 template<class T, class U> 5940 intrusive_ptr<T> const_pointer_cast(intrusive_ptr<U> const & r) noexcept; 5941 5942 template<class T, class U> 5943 intrusive_ptr<T> dynamic_pointer_cast(intrusive_ptr<U> const & r) noexcept; 5944 5945 template<class E, class T, class Y> 5946 std::basic_ostream<E, T> & operator<< (std::basic_ostream<E, T> & os, 5947 intrusive_ptr<Y> const & p); 5948}</code></pre> 5949</div> 5950</div> 5951</div> 5952<div class="sect2"> 5953<h3 id="intrusive_ptr_members">Members</h3> 5954<div class="sect3"> 5955<h4 id="intrusive_ptr_element_type">element_type</h4> 5956<div class="listingblock"> 5957<div class="content"> 5958<pre class="highlight"><code>typedef T element_type;</code></pre> 5959</div> 5960</div> 5961<div class="paragraph"> 5962<p>Provides the type of the template parameter T.</p> 5963</div> 5964</div> 5965<div class="sect3"> 5966<h4 id="intrusive_ptr_constructors">constructors</h4> 5967<div class="listingblock"> 5968<div class="content"> 5969<pre class="highlight"><code>intrusive_ptr() noexcept;</code></pre> 5970</div> 5971</div> 5972<div class="ulist none"> 5973<ul class="none"> 5974<li> 5975<p></p> 5976<div class="dlist"> 5977<dl> 5978<dt class="hdlist1">Postconditions</dt> 5979<dd> 5980<p><code>get() == 0</code>.</p> 5981</dd> 5982</dl> 5983</div> 5984</li> 5985</ul> 5986</div> 5987<div class="listingblock"> 5988<div class="content"> 5989<pre class="highlight"><code>intrusive_ptr(T * p, bool add_ref = true);</code></pre> 5990</div> 5991</div> 5992<div class="ulist none"> 5993<ul class="none"> 5994<li> 5995<p></p> 5996<div class="dlist"> 5997<dl> 5998<dt class="hdlist1">Effects</dt> 5999<dd> 6000<p><code>if(p != 0 && add_ref) intrusive_ptr_add_ref(p);</code>.</p> 6001</dd> 6002<dt class="hdlist1">Postconditions</dt> 6003<dd> 6004<p><code>get() == p</code>.</p> 6005</dd> 6006</dl> 6007</div> 6008</li> 6009</ul> 6010</div> 6011<div class="listingblock"> 6012<div class="content"> 6013<pre class="highlight"><code>intrusive_ptr(intrusive_ptr const & r);</code></pre> 6014</div> 6015</div> 6016<div class="listingblock"> 6017<div class="content"> 6018<pre class="highlight"><code>template<class Y> intrusive_ptr(intrusive_ptr<Y> const & r);</code></pre> 6019</div> 6020</div> 6021<div class="ulist none"> 6022<ul class="none"> 6023<li> 6024<p></p> 6025<div class="dlist"> 6026<dl> 6027<dt class="hdlist1">Effects</dt> 6028<dd> 6029<p><code>T * p = r.get(); if(p != 0) intrusive_ptr_add_ref(p);</code>.</p> 6030</dd> 6031<dt class="hdlist1">Postconditions</dt> 6032<dd> 6033<p><code>get() == r.get()</code>.</p> 6034</dd> 6035</dl> 6036</div> 6037</li> 6038</ul> 6039</div> 6040<div class="listingblock"> 6041<div class="content"> 6042<pre class="highlight"><code>intrusive_ptr(intrusive_ptr && r);</code></pre> 6043</div> 6044</div> 6045<div class="listingblock"> 6046<div class="content"> 6047<pre class="highlight"><code>template<class Y> intrusive_ptr(intrusive_ptr<Y> && r);</code></pre> 6048</div> 6049</div> 6050<div class="ulist none"> 6051<ul class="none"> 6052<li> 6053<p></p> 6054<div class="dlist"> 6055<dl> 6056<dt class="hdlist1">Postconditions</dt> 6057<dd> 6058<p><code>get()</code> equals the old value of <code>r.get()</code>. <code>r.get() == 0</code>.</p> 6059</dd> 6060</dl> 6061</div> 6062</li> 6063</ul> 6064</div> 6065</div> 6066<div class="sect3"> 6067<h4 id="intrusive_ptr_destructor">destructor</h4> 6068<div class="listingblock"> 6069<div class="content"> 6070<pre class="highlight"><code>~intrusive_ptr();</code></pre> 6071</div> 6072</div> 6073<div class="ulist none"> 6074<ul class="none"> 6075<li> 6076<p></p> 6077<div class="dlist"> 6078<dl> 6079<dt class="hdlist1">Effects</dt> 6080<dd> 6081<p><code>if(get() != 0) intrusive_ptr_release(get());</code>.</p> 6082</dd> 6083</dl> 6084</div> 6085</li> 6086</ul> 6087</div> 6088</div> 6089<div class="sect3"> 6090<h4 id="intrusive_ptr_assignment">assignment</h4> 6091<div class="listingblock"> 6092<div class="content"> 6093<pre class="highlight"><code>intrusive_ptr & operator=(intrusive_ptr const & r);</code></pre> 6094</div> 6095</div> 6096<div class="listingblock"> 6097<div class="content"> 6098<pre class="highlight"><code>template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> const & r);</code></pre> 6099</div> 6100</div> 6101<div class="listingblock"> 6102<div class="content"> 6103<pre class="highlight"><code>intrusive_ptr & operator=(T * r);</code></pre> 6104</div> 6105</div> 6106<div class="ulist none"> 6107<ul class="none"> 6108<li> 6109<p></p> 6110<div class="dlist"> 6111<dl> 6112<dt class="hdlist1">Effects</dt> 6113<dd> 6114<p>Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p> 6115</dd> 6116<dt class="hdlist1">Returns</dt> 6117<dd> 6118<p><code>*this</code>.</p> 6119</dd> 6120</dl> 6121</div> 6122</li> 6123</ul> 6124</div> 6125<div class="listingblock"> 6126<div class="content"> 6127<pre class="highlight"><code>intrusive_ptr & operator=(intrusive_ptr && r);</code></pre> 6128</div> 6129</div> 6130<div class="listingblock"> 6131<div class="content"> 6132<pre class="highlight"><code>template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> && r);</code></pre> 6133</div> 6134</div> 6135<div class="ulist none"> 6136<ul class="none"> 6137<li> 6138<p></p> 6139<div class="dlist"> 6140<dl> 6141<dt class="hdlist1">Effects</dt> 6142<dd> 6143<p>Equivalent to <code>intrusive_ptr(std::move(r)).swap(*this)</code>.</p> 6144</dd> 6145<dt class="hdlist1">Returns</dt> 6146<dd> 6147<p><code>*this</code>.</p> 6148</dd> 6149</dl> 6150</div> 6151</li> 6152</ul> 6153</div> 6154</div> 6155<div class="sect3"> 6156<h4 id="intrusive_ptr_reset">reset</h4> 6157<div class="listingblock"> 6158<div class="content"> 6159<pre class="highlight"><code>void reset();</code></pre> 6160</div> 6161</div> 6162<div class="ulist none"> 6163<ul class="none"> 6164<li> 6165<p></p> 6166<div class="dlist"> 6167<dl> 6168<dt class="hdlist1">Effects</dt> 6169<dd> 6170<p>Equivalent to <code>intrusive_ptr().swap(*this)</code>.</p> 6171</dd> 6172</dl> 6173</div> 6174</li> 6175</ul> 6176</div> 6177<div class="listingblock"> 6178<div class="content"> 6179<pre class="highlight"><code>void reset(T * r);</code></pre> 6180</div> 6181</div> 6182<div class="ulist none"> 6183<ul class="none"> 6184<li> 6185<p></p> 6186<div class="dlist"> 6187<dl> 6188<dt class="hdlist1">Effects</dt> 6189<dd> 6190<p>Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p> 6191</dd> 6192</dl> 6193</div> 6194</li> 6195</ul> 6196</div> 6197<div class="listingblock"> 6198<div class="content"> 6199<pre class="highlight"><code>void reset(T * r, bool add_ref);</code></pre> 6200</div> 6201</div> 6202<div class="ulist none"> 6203<ul class="none"> 6204<li> 6205<p></p> 6206<div class="dlist"> 6207<dl> 6208<dt class="hdlist1">Effects</dt> 6209<dd> 6210<p>Equivalent to <code>intrusive_ptr(r, add_ref).swap(*this)</code>.</p> 6211</dd> 6212</dl> 6213</div> 6214</li> 6215</ul> 6216</div> 6217</div> 6218<div class="sect3"> 6219<h4 id="intrusive_ptr_indirection">indirection</h4> 6220<div class="listingblock"> 6221<div class="content"> 6222<pre class="highlight"><code>T & operator*() const noexcept;</code></pre> 6223</div> 6224</div> 6225<div class="ulist none"> 6226<ul class="none"> 6227<li> 6228<p></p> 6229<div class="dlist"> 6230<dl> 6231<dt class="hdlist1">Requirements</dt> 6232<dd> 6233<p><code>get() != 0</code>.</p> 6234</dd> 6235<dt class="hdlist1">Returns</dt> 6236<dd> 6237<p><code>*get()</code>.</p> 6238</dd> 6239</dl> 6240</div> 6241</li> 6242</ul> 6243</div> 6244<div class="listingblock"> 6245<div class="content"> 6246<pre class="highlight"><code>T * operator->() const noexcept;</code></pre> 6247</div> 6248</div> 6249<div class="ulist none"> 6250<ul class="none"> 6251<li> 6252<p></p> 6253<div class="dlist"> 6254<dl> 6255<dt class="hdlist1">Requirements</dt> 6256<dd> 6257<p><code>get() != 0</code>.</p> 6258</dd> 6259<dt class="hdlist1">Returns</dt> 6260<dd> 6261<p><code>get()</code>.</p> 6262</dd> 6263</dl> 6264</div> 6265</li> 6266</ul> 6267</div> 6268</div> 6269<div class="sect3"> 6270<h4 id="intrusive_ptr_get">get</h4> 6271<div class="listingblock"> 6272<div class="content"> 6273<pre class="highlight"><code>T * get() const noexcept;</code></pre> 6274</div> 6275</div> 6276<div class="ulist none"> 6277<ul class="none"> 6278<li> 6279<p></p> 6280<div class="dlist"> 6281<dl> 6282<dt class="hdlist1">Returns</dt> 6283<dd> 6284<p>the stored pointer.</p> 6285</dd> 6286</dl> 6287</div> 6288</li> 6289</ul> 6290</div> 6291</div> 6292<div class="sect3"> 6293<h4 id="intrusive_ptr_detach">detach</h4> 6294<div class="listingblock"> 6295<div class="content"> 6296<pre class="highlight"><code>T * detach() noexcept;</code></pre> 6297</div> 6298</div> 6299<div class="ulist none"> 6300<ul class="none"> 6301<li> 6302<p></p> 6303<div class="dlist"> 6304<dl> 6305<dt class="hdlist1">Returns</dt> 6306<dd> 6307<p>the stored pointer.</p> 6308</dd> 6309<dt class="hdlist1">Postconditions</dt> 6310<dd> 6311<p><code>get() == 0</code>.</p> 6312</dd> 6313</dl> 6314</div> 6315</li> 6316</ul> 6317</div> 6318<div class="admonitionblock note"> 6319<table> 6320<tr> 6321<td class="icon"> 6322<div class="title">Note</div> 6323</td> 6324<td class="content"> 6325The returned pointer has an elevated reference count. This allows conversion of an <code>intrusive_ptr</code> 6326back to a raw pointer, without the performance overhead of acquiring and dropping an extra reference. 6327It can be viewed as the complement of the non-reference-incrementing constructor. 6328</td> 6329</tr> 6330</table> 6331</div> 6332<div class="admonitionblock caution"> 6333<table> 6334<tr> 6335<td class="icon"> 6336<div class="title">Caution</div> 6337</td> 6338<td class="content"> 6339Using <code>detach</code> escapes the safety of automatic reference counting provided by <code>intrusive_ptr</code>. 6340It should by used only where strictly necessary (such as when interfacing to an existing API), and when 6341the implications are thoroughly understood. 6342</td> 6343</tr> 6344</table> 6345</div> 6346</div> 6347<div class="sect3"> 6348<h4 id="intrusive_ptr_conversions">conversions</h4> 6349<div class="listingblock"> 6350<div class="content"> 6351<pre class="highlight"><code>explicit operator bool () const noexcept;</code></pre> 6352</div> 6353</div> 6354<div class="ulist none"> 6355<ul class="none"> 6356<li> 6357<p></p> 6358<div class="dlist"> 6359<dl> 6360<dt class="hdlist1">Returns</dt> 6361<dd> 6362<p><code>get() != 0</code>.</p> 6363</dd> 6364</dl> 6365</div> 6366</li> 6367</ul> 6368</div> 6369<div class="admonitionblock note"> 6370<table> 6371<tr> 6372<td class="icon"> 6373<div class="title">Note</div> 6374</td> 6375<td class="content"> 6376This conversion operator allows <code>intrusive_ptr</code> objects to be used in boolean contexts, 6377like <code>if (p && p->valid()) {}</code>. 6378</td> 6379</tr> 6380</table> 6381</div> 6382<div class="admonitionblock note"> 6383<table> 6384<tr> 6385<td class="icon"> 6386<div class="title">Note</div> 6387</td> 6388<td class="content"> 6389On C++03 compilers, the return value is of an unspecified type. 6390</td> 6391</tr> 6392</table> 6393</div> 6394</div> 6395<div class="sect3"> 6396<h4 id="intrusive_ptr_swap">swap</h4> 6397<div class="listingblock"> 6398<div class="content"> 6399<pre class="highlight"><code>void swap(intrusive_ptr & b) noexcept;</code></pre> 6400</div> 6401</div> 6402<div class="ulist none"> 6403<ul class="none"> 6404<li> 6405<p></p> 6406<div class="dlist"> 6407<dl> 6408<dt class="hdlist1">Effects</dt> 6409<dd> 6410<p>Exchanges the contents of the two smart pointers.</p> 6411</dd> 6412</dl> 6413</div> 6414</li> 6415</ul> 6416</div> 6417</div> 6418</div> 6419<div class="sect2"> 6420<h3 id="intrusive_ptr_free_functions">Free Functions</h3> 6421<div class="sect3"> 6422<h4 id="intrusive_ptr_comparison">comparison</h4> 6423<div class="listingblock"> 6424<div class="content"> 6425<pre class="highlight"><code>template<class T, class U> 6426 bool operator==(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b) noexcept;</code></pre> 6427</div> 6428</div> 6429<div class="ulist none"> 6430<ul class="none"> 6431<li> 6432<p></p> 6433<div class="dlist"> 6434<dl> 6435<dt class="hdlist1">Returns</dt> 6436<dd> 6437<p><code>a.get() == b.get()</code>.</p> 6438</dd> 6439</dl> 6440</div> 6441</li> 6442</ul> 6443</div> 6444<div class="listingblock"> 6445<div class="content"> 6446<pre class="highlight"><code>template<class T, class U> 6447 bool operator!=(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b) noexcept;</code></pre> 6448</div> 6449</div> 6450<div class="ulist none"> 6451<ul class="none"> 6452<li> 6453<p></p> 6454<div class="dlist"> 6455<dl> 6456<dt class="hdlist1">Returns</dt> 6457<dd> 6458<p><code>a.get() != b.get()</code>.</p> 6459</dd> 6460</dl> 6461</div> 6462</li> 6463</ul> 6464</div> 6465<div class="listingblock"> 6466<div class="content"> 6467<pre class="highlight"><code>template<class T, class U> 6468 bool operator==(intrusive_ptr<T> const & a, U * b) noexcept;</code></pre> 6469</div> 6470</div> 6471<div class="ulist none"> 6472<ul class="none"> 6473<li> 6474<p></p> 6475<div class="dlist"> 6476<dl> 6477<dt class="hdlist1">Returns</dt> 6478<dd> 6479<p><code>a.get() == b</code>.</p> 6480</dd> 6481</dl> 6482</div> 6483</li> 6484</ul> 6485</div> 6486<div class="listingblock"> 6487<div class="content"> 6488<pre class="highlight"><code>template<class T, class U> 6489 bool operator!=(intrusive_ptr<T> const & a, U * b) noexcept;</code></pre> 6490</div> 6491</div> 6492<div class="ulist none"> 6493<ul class="none"> 6494<li> 6495<p></p> 6496<div class="dlist"> 6497<dl> 6498<dt class="hdlist1">Returns</dt> 6499<dd> 6500<p><code>a.get() != b</code>.</p> 6501</dd> 6502</dl> 6503</div> 6504</li> 6505</ul> 6506</div> 6507<div class="listingblock"> 6508<div class="content"> 6509<pre class="highlight"><code>template<class T, class U> 6510 bool operator==(T * a, intrusive_ptr<U> const & b) noexcept;</code></pre> 6511</div> 6512</div> 6513<div class="ulist none"> 6514<ul class="none"> 6515<li> 6516<p></p> 6517<div class="dlist"> 6518<dl> 6519<dt class="hdlist1">Returns</dt> 6520<dd> 6521<p><code>a == b.get()</code>.</p> 6522</dd> 6523</dl> 6524</div> 6525</li> 6526</ul> 6527</div> 6528<div class="listingblock"> 6529<div class="content"> 6530<pre class="highlight"><code>template<class T, class U> 6531 bool operator!=(T * a, intrusive_ptr<U> const & b) noexcept;</code></pre> 6532</div> 6533</div> 6534<div class="ulist none"> 6535<ul class="none"> 6536<li> 6537<p></p> 6538<div class="dlist"> 6539<dl> 6540<dt class="hdlist1">Returns</dt> 6541<dd> 6542<p><code>a != b.get()</code>.</p> 6543</dd> 6544</dl> 6545</div> 6546</li> 6547</ul> 6548</div> 6549<div class="listingblock"> 6550<div class="content"> 6551<pre class="highlight"><code>template<class T> 6552 bool operator<(intrusive_ptr<T> const & a, intrusive_ptr<T> const & b) noexcept;</code></pre> 6553</div> 6554</div> 6555<div class="ulist none"> 6556<ul class="none"> 6557<li> 6558<p></p> 6559<div class="dlist"> 6560<dl> 6561<dt class="hdlist1">Returns</dt> 6562<dd> 6563<p><code>std::less<T *>()(a.get(), b.get())</code>.</p> 6564</dd> 6565</dl> 6566</div> 6567</li> 6568</ul> 6569</div> 6570<div class="admonitionblock note"> 6571<table> 6572<tr> 6573<td class="icon"> 6574<div class="title">Note</div> 6575</td> 6576<td class="content"> 6577Allows <code>intrusive_ptr</code> objects to be used as keys in associative containers. 6578</td> 6579</tr> 6580</table> 6581</div> 6582</div> 6583<div class="sect3"> 6584<h4 id="intrusive_ptr_swap_2">swap</h4> 6585<div class="listingblock"> 6586<div class="content"> 6587<pre class="highlight"><code>template<class T> void swap(intrusive_ptr<T> & a, intrusive_ptr<T> & b) noexcept;</code></pre> 6588</div> 6589</div> 6590<div class="ulist none"> 6591<ul class="none"> 6592<li> 6593<p></p> 6594<div class="dlist"> 6595<dl> 6596<dt class="hdlist1">Effects</dt> 6597<dd> 6598<p>Equivalent to <code>a.swap(b)</code>.</p> 6599</dd> 6600</dl> 6601</div> 6602</li> 6603</ul> 6604</div> 6605</div> 6606<div class="sect3"> 6607<h4 id="intrusive_ptr_get_pointer">get_pointer</h4> 6608<div class="listingblock"> 6609<div class="content"> 6610<pre class="highlight"><code>template<class T> T * get_pointer(intrusive_ptr<T> const & p) noexcept;</code></pre> 6611</div> 6612</div> 6613<div class="ulist none"> 6614<ul class="none"> 6615<li> 6616<p></p> 6617<div class="dlist"> 6618<dl> 6619<dt class="hdlist1">Returns</dt> 6620<dd> 6621<p><code>p.get()</code>.</p> 6622</dd> 6623</dl> 6624</div> 6625</li> 6626</ul> 6627</div> 6628<div class="admonitionblock note"> 6629<table> 6630<tr> 6631<td class="icon"> 6632<div class="title">Note</div> 6633</td> 6634<td class="content"> 6635Provided as an aid to generic programming. Used by <code>mem_fn</code>. 6636</td> 6637</tr> 6638</table> 6639</div> 6640</div> 6641<div class="sect3"> 6642<h4 id="intrusive_ptr_static_pointer_cast">static_pointer_cast</h4> 6643<div class="listingblock"> 6644<div class="content"> 6645<pre class="highlight"><code>template<class T, class U> 6646 intrusive_ptr<T> static_pointer_cast(intrusive_ptr<U> const & r) noexcept;</code></pre> 6647</div> 6648</div> 6649<div class="ulist none"> 6650<ul class="none"> 6651<li> 6652<p></p> 6653<div class="dlist"> 6654<dl> 6655<dt class="hdlist1">Returns</dt> 6656<dd> 6657<p><code>intrusive_ptr<T>(static_cast<T*>(r.get()))</code>.</p> 6658</dd> 6659</dl> 6660</div> 6661</li> 6662</ul> 6663</div> 6664</div> 6665<div class="sect3"> 6666<h4 id="intrusive_ptr_const_pointer_cast">const_pointer_cast</h4> 6667<div class="listingblock"> 6668<div class="content"> 6669<pre class="highlight"><code>template<class T, class U> 6670 intrusive_ptr<T> const_pointer_cast(intrusive_ptr<U> const & r) noexcept;</code></pre> 6671</div> 6672</div> 6673<div class="ulist none"> 6674<ul class="none"> 6675<li> 6676<p></p> 6677<div class="dlist"> 6678<dl> 6679<dt class="hdlist1">Returns</dt> 6680<dd> 6681<p><code>intrusive_ptr<T>(const_cast<T*>(r.get()))</code>.</p> 6682</dd> 6683</dl> 6684</div> 6685</li> 6686</ul> 6687</div> 6688</div> 6689<div class="sect3"> 6690<h4 id="intrusive_ptr_dynamic_pointer_cast">dynamic_pointer_cast</h4> 6691<div class="listingblock"> 6692<div class="content"> 6693<pre class="highlight"><code>template<class T, class U> 6694 intrusive_ptr<T> dynamic_pointer_cast(intrusive_ptr<U> const & r) noexcept;</code></pre> 6695</div> 6696</div> 6697<div class="ulist none"> 6698<ul class="none"> 6699<li> 6700<p></p> 6701<div class="dlist"> 6702<dl> 6703<dt class="hdlist1">Returns</dt> 6704<dd> 6705<p><code>intrusive_ptr<T>(dynamic_cast<T*>(r.get()))</code>.</p> 6706</dd> 6707</dl> 6708</div> 6709</li> 6710</ul> 6711</div> 6712</div> 6713<div class="sect3"> 6714<h4 id="intrusive_ptr_operator">operator<<</h4> 6715<div class="listingblock"> 6716<div class="content"> 6717<pre class="highlight"><code>template<class E, class T, class Y> 6718 std::basic_ostream<E, T> & operator<< (std::basic_ostream<E, T> & os, 6719 intrusive_ptr<Y> const & p);</code></pre> 6720</div> 6721</div> 6722<div class="ulist none"> 6723<ul class="none"> 6724<li> 6725<p></p> 6726<div class="dlist"> 6727<dl> 6728<dt class="hdlist1">Effects</dt> 6729<dd> 6730<p><code>os << p.get();</code>.</p> 6731</dd> 6732<dt class="hdlist1">Returns</dt> 6733<dd> 6734<p><code>os</code>.</p> 6735</dd> 6736</dl> 6737</div> 6738</li> 6739</ul> 6740</div> 6741</div> 6742</div> 6743</div> 6744</div> 6745<div class="sect1"> 6746<h2 id="intrusive_ref_counter">intrusive_ref_counter</h2> 6747<div class="sectionbody"> 6748<div class="sect2"> 6749<h3 id="intrusive_ref_counter_description">Description</h3> 6750<div class="paragraph"> 6751<p>The <code>intrusive_ref_counter</code> class template implements a reference counter for 6752a derived user’s class that is intended to be used with <code>intrusive_ptr</code>. The 6753base class has associated <code>intrusive_ptr_add_ref</code> and <code>intrusive_ptr_release</code> 6754functions which modify the reference counter as needed and destroy the user’s 6755object when the counter drops to zero.</p> 6756</div> 6757<div class="paragraph"> 6758<p>The class template is parameterized on <code>Derived</code> and <code>CounterPolicy</code> 6759parameters. The first parameter is the user’s class that derives from 6760<code>intrusive_ref_counter</code>. This type is needed in order to destroy the object 6761correctly when there are no references to it left.</p> 6762</div> 6763<div class="paragraph"> 6764<p>The second parameter is a policy that defines the nature of the reference 6765counter. The library provides two such policies: <code>thread_unsafe_counter</code> and 6766<code>thread_safe_counter</code>. The former instructs the <code>intrusive_ref_counter</code> base 6767class to use a counter only suitable for a single-threaded use. Pointers to a 6768single object that uses this kind of reference counter must not be used in 6769different threads. The latter policy makes the reference counter thread-safe, 6770unless the target platform doesn’t support threading. Since in modern systems 6771support for threading is common, the default counter policy is 6772<code>thread_safe_counter</code>.</p> 6773</div> 6774</div> 6775<div class="sect2"> 6776<h3 id="intrusive_ref_counter_synopsis">Synopsis</h3> 6777<div class="paragraph"> 6778<p><code>intrusive_ref_counter</code> is defined in 6779<code><boost/smart_ptr/intrusive_ref_counter.hpp></code>.</p> 6780</div> 6781<div class="listingblock"> 6782<div class="content"> 6783<pre class="highlight"><code>namespace boost { 6784 struct thread_unsafe_counter; 6785 struct thread_safe_counter; 6786 6787 template<class Derived, class CounterPolicy = thread_safe_counter> 6788 class intrusive_ref_counter { 6789 public: 6790 intrusive_ref_counter() noexcept; 6791 intrusive_ref_counter(const intrusive_ref_counter& v) noexcept; 6792 6793 intrusive_ref_counter& operator=(const intrusive_ref_counter& v) noexcept; 6794 6795 unsigned int use_count() const noexcept; 6796 6797 protected: 6798 ~intrusive_ref_counter() = default; 6799 }; 6800 6801 template<class Derived, class CounterPolicy> 6802 void intrusive_ptr_add_ref( 6803 const intrusive_ref_counter<Derived, CounterPolicy>* p) noexcept; 6804 6805 template<class Derived, class CounterPolicy> 6806 void intrusive_ptr_release( 6807 const intrusive_ref_counter<Derived, CounterPolicy>* p) noexcept; 6808}</code></pre> 6809</div> 6810</div> 6811</div> 6812<div class="sect2"> 6813<h3 id="intrusive_ref_counter_members">Members</h3> 6814<div class="sect3"> 6815<h4 id="intrusive_ref_counter_constructors">Constructors</h4> 6816<div class="listingblock"> 6817<div class="content"> 6818<pre class="highlight"><code>intrusive_ref_counter() noexcept;</code></pre> 6819</div> 6820</div> 6821<div class="listingblock"> 6822<div class="content"> 6823<pre class="highlight"><code>intrusive_ref_counter(const intrusive_ref_counter&) noexcept;</code></pre> 6824</div> 6825</div> 6826<div class="ulist none"> 6827<ul class="none"> 6828<li> 6829<p></p> 6830<div class="dlist"> 6831<dl> 6832<dt class="hdlist1">Postconditions</dt> 6833<dd> 6834<p><code>use_count() == 0</code>.</p> 6835</dd> 6836</dl> 6837</div> 6838</li> 6839</ul> 6840</div> 6841<div class="admonitionblock note"> 6842<table> 6843<tr> 6844<td class="icon"> 6845<div class="title">Note</div> 6846</td> 6847<td class="content"> 6848The pointer to the constructed object is expected to be passed to 6849<code>intrusive_ptr</code> constructor, assignment operator or <code>reset</code> method, which 6850would increment the reference counter. 6851</td> 6852</tr> 6853</table> 6854</div> 6855</div> 6856<div class="sect3"> 6857<h4 id="intrusive_ref_counter_destructor">Destructor</h4> 6858<div class="listingblock"> 6859<div class="content"> 6860<pre class="highlight"><code>~intrusive_ref_counter();</code></pre> 6861</div> 6862</div> 6863<div class="ulist none"> 6864<ul class="none"> 6865<li> 6866<p></p> 6867<div class="dlist"> 6868<dl> 6869<dt class="hdlist1">Effects</dt> 6870<dd> 6871<p>Destroys the counter object.</p> 6872</dd> 6873</dl> 6874</div> 6875</li> 6876</ul> 6877</div> 6878<div class="admonitionblock note"> 6879<table> 6880<tr> 6881<td class="icon"> 6882<div class="title">Note</div> 6883</td> 6884<td class="content"> 6885The destructor is protected so that the object can only be destroyed 6886through the <code>Derived</code> class. 6887</td> 6888</tr> 6889</table> 6890</div> 6891</div> 6892<div class="sect3"> 6893<h4 id="intrusive_ref_counter_assignment">Assignment</h4> 6894<div class="listingblock"> 6895<div class="content"> 6896<pre class="highlight"><code>intrusive_ref_counter& operator=(const intrusive_ref_counter& v) noexcept;</code></pre> 6897</div> 6898</div> 6899<div class="ulist none"> 6900<ul class="none"> 6901<li> 6902<p></p> 6903<div class="dlist"> 6904<dl> 6905<dt class="hdlist1">Effects</dt> 6906<dd> 6907<p>Does nothing, reference counter is not modified.</p> 6908</dd> 6909</dl> 6910</div> 6911</li> 6912</ul> 6913</div> 6914</div> 6915<div class="sect3"> 6916<h4 id="intrusive_ref_counter_use_count">use_count</h4> 6917<div class="listingblock"> 6918<div class="content"> 6919<pre class="highlight"><code>unsigned int use_count() const noexcept;</code></pre> 6920</div> 6921</div> 6922<div class="ulist none"> 6923<ul class="none"> 6924<li> 6925<p></p> 6926<div class="dlist"> 6927<dl> 6928<dt class="hdlist1">Returns</dt> 6929<dd> 6930<p>The current value of the reference counter.</p> 6931</dd> 6932</dl> 6933</div> 6934</li> 6935</ul> 6936</div> 6937<div class="admonitionblock note"> 6938<table> 6939<tr> 6940<td class="icon"> 6941<div class="title">Note</div> 6942</td> 6943<td class="content"> 6944The returned value may not be actual in multi-threaded applications. 6945</td> 6946</tr> 6947</table> 6948</div> 6949</div> 6950</div> 6951<div class="sect2"> 6952<h3 id="intrusive_ref_counter_free_functions">Free Functions</h3> 6953<div class="sect3"> 6954<h4 id="intrusive_ref_counter_intrusive_ptr_add_ref">intrusive_ptr_add_ref</h4> 6955<div class="listingblock"> 6956<div class="content"> 6957<pre class="highlight"><code>template<class Derived, class CounterPolicy> 6958 void intrusive_ptr_add_ref( 6959 const intrusive_ref_counter<Derived, CounterPolicy>* p) noexcept;</code></pre> 6960</div> 6961</div> 6962<div class="ulist none"> 6963<ul class="none"> 6964<li> 6965<p></p> 6966<div class="dlist"> 6967<dl> 6968<dt class="hdlist1">Effects</dt> 6969<dd> 6970<p>Increments the reference counter.</p> 6971</dd> 6972</dl> 6973</div> 6974</li> 6975</ul> 6976</div> 6977</div> 6978<div class="sect3"> 6979<h4 id="intrusive_ref_counter_intrusive_ptr_release">intrusive_ptr_release</h4> 6980<div class="listingblock"> 6981<div class="content"> 6982<pre class="highlight"><code>template<class Derived, class CounterPolicy> 6983 void intrusive_ptr_release( 6984 const intrusive_ref_counter<Derived, CounterPolicy>* p) noexcept;</code></pre> 6985</div> 6986</div> 6987<div class="ulist none"> 6988<ul class="none"> 6989<li> 6990<p></p> 6991<div class="dlist"> 6992<dl> 6993<dt class="hdlist1">Effects</dt> 6994<dd> 6995<p>Decrements the reference counter. If the reference counter reaches 69960, calls <code>delete static_cast<const Derived*>(p)</code>.</p> 6997</dd> 6998</dl> 6999</div> 7000</li> 7001</ul> 7002</div> 7003</div> 7004</div> 7005</div> 7006</div> 7007<div class="sect1"> 7008<h2 id="local_shared_ptr">local_shared_ptr: Shared Ownership within a Single Thread</h2> 7009<div class="sectionbody"> 7010<div class="sect2"> 7011<h3 id="local_shared_ptr_description">Description</h3> 7012<div class="paragraph"> 7013<p><code>local_shared_ptr</code> is nearly identical to <code>shared_ptr</code>, with the only difference of note being that its reference count is 7014updated with non-atomic operations. As such, a <code>local_shared_ptr</code> and all its copies must reside in (be local to) a single 7015thread (hence the name.)</p> 7016</div> 7017<div class="paragraph"> 7018<p><code>local_shared_ptr</code> can be converted to <code>shared_ptr</code> and vice versa. Creating a <code>local_shared_ptr</code> from a <code>shared_ptr</code> creates 7019a new local reference count; this means that two <code>local_shared_ptr</code> instances, both created from the same <code>shared_ptr</code>, refer 7020to the same object but don’t share the same count, and as such, can safely be used by two different threads.</p> 7021</div> 7022<div class="listingblock"> 7023<div class="title">Code Example 9. Two local_shared_ptr instances created from a shared_ptr</div> 7024<div class="content"> 7025<pre class="highlight"><code>shared_ptr<X> p1( new X ); 7026 7027local_shared_ptr<X> p2( p1 ); // p2.local_use_count() == 1 7028local_shared_ptr<X> p3( p1 ); // p3.local_use_count() also 1</code></pre> 7029</div> 7030</div> 7031<div class="paragraph"> 7032<p>Creating the second <code>local_shared_ptr</code> from the first one, however, does lead to the two sharing the same count:</p> 7033</div> 7034<div class="listingblock"> 7035<div class="title">Code Example 10. A local_shared_ptr created from another local_shared_ptr</div> 7036<div class="content"> 7037<pre class="highlight"><code>shared_ptr<X> p1( new X ); 7038 7039local_shared_ptr<X> p2( p1 ); // p2.local_use_count() == 1 7040local_shared_ptr<X> p3( p2 ); // p3.local_use_count() == 2</code></pre> 7041</div> 7042</div> 7043<div class="paragraph"> 7044<p>Two <code>shared_ptr</code> instances created from the same <code>local_shared_ptr</code> do share ownership:</p> 7045</div> 7046<div class="listingblock"> 7047<div class="title">Code Example 11. Two shared_ptr instances created from a local_shared_ptr</div> 7048<div class="content"> 7049<pre class="highlight"><code>local_shared_ptr<X> p1( new X ); 7050 7051shared_ptr<X> p2( p1 ); // p2.use_count() == 2 7052shared_ptr<X> p3( p1 ); // p3.use_count() == 3</code></pre> 7053</div> 7054</div> 7055<div class="paragraph"> 7056<p>Here <code>p2.use_count()</code> is 2, because <code>p1</code> holds a reference, too.</p> 7057</div> 7058<div class="paragraph"> 7059<p>One can think of <code>local_shared_ptr<T></code> as <code>shared_ptr<shared_ptr<T>></code>, with the outer <code>shared_ptr</code> using non-atomic operations for 7060its count. Converting from <code>local_shared_ptr</code> to <code>shared_ptr</code> gives you a copy of the inner <code>shared_ptr</code>; converting from <code>shared_ptr</code> 7061wraps it into an outer <code>shared_ptr</code> with a non-atomic use count (conceptually speaking) and returns the result.</p> 7062</div> 7063</div> 7064<div class="sect2"> 7065<h3 id="local_shared_ptr_synopsis">Synopsis</h3> 7066<div class="paragraph"> 7067<p><code>local_shared_ptr</code> is defined in <code><boost/smart_ptr/local_shared_ptr.hpp></code>.</p> 7068</div> 7069<div class="listingblock"> 7070<div class="content"> 7071<pre class="highlight"><code>namespace boost { 7072 7073 template<class T> class local_shared_ptr { 7074 public: 7075 7076 typedef /*see below*/ element_type; 7077 7078 // constructors 7079 7080 constexpr local_shared_ptr() noexcept; 7081 constexpr local_shared_ptr(std::nullptr_t) noexcept; 7082 7083 template<class Y> explicit local_shared_ptr(Y * p); 7084 7085 template<class Y, class D> local_shared_ptr(Y * p, D d); 7086 template<class D> local_shared_ptr(std::nullptr_t p, D d); 7087 7088 template<class Y, class D, class A> local_shared_ptr(Y * p, D d, A a); 7089 template<class D, class A> local_shared_ptr(std::nullptr_t p, D d, A a); 7090 7091 local_shared_ptr(local_shared_ptr const & r) noexcept; 7092 template<class Y> local_shared_ptr(local_shared_ptr<Y> const & r) noexcept; 7093 7094 local_shared_ptr(local_shared_ptr && r) noexcept; 7095 template<class Y> local_shared_ptr(local_shared_ptr<Y> && r) noexcept; 7096 7097 template<class Y> local_shared_ptr( shared_ptr<Y> const & r ); 7098 template<class Y> local_shared_ptr( shared_ptr<Y> && r ); 7099 7100 template<class Y> local_shared_ptr(local_shared_ptr<Y> const & r, element_type * p) noexcept; 7101 template<class Y> local_shared_ptr(local_shared_ptr<Y> && r, element_type * p) noexcept; 7102 7103 template<class Y, class D> local_shared_ptr(std::unique_ptr<Y, D> && r); 7104 7105 // destructor 7106 7107 ~local_shared_ptr() noexcept; 7108 7109 // assignment 7110 7111 local_shared_ptr & operator=(local_shared_ptr const & r) noexcept; 7112 template<class Y> local_shared_ptr & operator=(local_shared_ptr<Y> const & r) noexcept; 7113 7114 local_shared_ptr & operator=(local_shared_ptr const && r) noexcept; 7115 template<class Y> local_shared_ptr & operator=(local_shared_ptr<Y> const && r) noexcept; 7116 7117 template<class Y, class D> local_shared_ptr & operator=(std::unique_ptr<Y, D> && r); 7118 7119 local_shared_ptr & operator=(std::nullptr_t) noexcept; 7120 7121 // reset 7122 7123 void reset() noexcept; 7124 7125 template<class Y> void reset(Y * p); 7126 template<class Y, class D> void reset(Y * p, D d); 7127 template<class Y, class D, class A> void reset(Y * p, D d, A a); 7128 7129 template<class Y> void reset(local_shared_ptr<Y> const & r, element_type * p) noexcept; 7130 template<class Y> void reset(local_shared_ptr<Y> && r, element_type * p) noexcept; 7131 7132 // accessors 7133 7134 T & operator*() const noexcept; // only valid when T is not an array type 7135 T * operator->() const noexcept; // only valid when T is not an array type 7136 7137 // only valid when T is an array type 7138 element_type & operator[](std::ptrdiff_t i) const noexcept; 7139 7140 element_type * get() const noexcept; 7141 7142 long local_use_count() const noexcept; 7143 7144 // conversions 7145 7146 explicit operator bool() const noexcept; 7147 7148 template<class Y> operator shared_ptr<Y>() const noexcept; 7149 template<class Y> operator weak_ptr<Y>() const noexcept; 7150 7151 // swap 7152 7153 void swap(local_shared_ptr & b) noexcept; 7154 7155 // owner_before 7156 7157 template<class Y> bool owner_before(local_shared_ptr<Y> const & r) const noexcept; 7158 7159 // owner_equals 7160 7161 template<class Y> bool owner_equals(local_shared_ptr<Y> const & r) const noexcept; 7162 }; 7163 7164 // comparisons 7165 7166 template<class T, class U> 7167 bool operator==(local_shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept; 7168 template<class T, class U> 7169 bool operator==(local_shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 7170 template<class T, class U> 7171 bool operator==(shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept; 7172 7173 template<class T, class U> 7174 bool operator!=(local_shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept; 7175 template<class T, class U> 7176 bool operator!=(local_shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept; 7177 template<class T, class U> 7178 bool operator!=(shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept; 7179 7180 template<class T> bool operator==(local_shared_ptr<T> const & p, std::nullptr_t) noexcept; 7181 template<class T> bool operator==(std::nullptr_t, local_shared_ptr<T> const & p) noexcept; 7182 7183 template<class T> bool operator!=(local_shared_ptr<T> const & p, std::nullptr_t) noexcept; 7184 template<class T> bool operator!=(std::nullptr_t, local_shared_ptr<T> const & p) noexcept; 7185 7186 template<class T, class U> 7187 bool operator<(local_shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept; 7188 7189 // swap 7190 7191 template<class T> void swap(local_shared_ptr<T> & a, local_shared_ptr<T> & b) noexcept; 7192 7193 // get_pointer 7194 7195 template<class T> 7196 typename local_shared_ptr<T>::element_type * 7197 get_pointer(local_shared_ptr<T> const & p) noexcept; 7198 7199 // casts 7200 7201 template<class T, class U> 7202 local_shared_ptr<T> static_pointer_cast(local_shared_ptr<U> const & r) noexcept; 7203 7204 template<class T, class U> 7205 local_shared_ptr<T> const_pointer_cast(local_shared_ptr<U> const & r) noexcept; 7206 7207 template<class T, class U> 7208 local_shared_ptr<T> dynamic_pointer_cast(local_shared_ptr<U> const & r) noexcept; 7209 7210 template<class T, class U> 7211 local_shared_ptr<T> reinterpret_pointer_cast(local_shared_ptr<U> const & r) noexcept; 7212 7213 // stream I/O 7214 7215 template<class E, class T, class Y> 7216 std::basic_ostream<E, T> & 7217 operator<< (std::basic_ostream<E, T> & os, local_shared_ptr<Y> const & p); 7218 7219 // get_deleter 7220 7221 template<class D, class T> D * get_deleter(local_shared_ptr<T> const & p) noexcept; 7222}</code></pre> 7223</div> 7224</div> 7225</div> 7226<div class="sect2"> 7227<h3 id="local_shared_ptr_members">Members</h3> 7228<div class="sect3"> 7229<h4 id="local_shared_ptr_element_type">element_type</h4> 7230<div class="listingblock"> 7231<div class="content"> 7232<pre class="highlight"><code>typedef ... element_type;</code></pre> 7233</div> 7234</div> 7235<div class="paragraph"> 7236<p><code>element_type</code> is <code>T</code> when <code>T</code> is not an array type, and <code>U</code> when <code>T</code> is <code>U[]</code> or <code>U[N]</code>.</p> 7237</div> 7238</div> 7239<div class="sect3"> 7240<h4 id="local_shared_ptr_default_constructor">default constructor</h4> 7241<div class="listingblock"> 7242<div class="content"> 7243<pre class="highlight"><code>constexpr local_shared_ptr() noexcept;</code></pre> 7244</div> 7245</div> 7246<div class="listingblock"> 7247<div class="content"> 7248<pre class="highlight"><code>constexpr local_shared_ptr(std::nullptr_t) noexcept;</code></pre> 7249</div> 7250</div> 7251<div class="ulist none"> 7252<ul class="none"> 7253<li> 7254<p></p> 7255<div class="dlist"> 7256<dl> 7257<dt class="hdlist1">Effects</dt> 7258<dd> 7259<p>Constructs an empty <code>local_shared_ptr</code>.</p> 7260</dd> 7261<dt class="hdlist1">Postconditions</dt> 7262<dd> 7263<p><code>local_use_count() == 0 && get() == 0</code>.</p> 7264</dd> 7265</dl> 7266</div> 7267</li> 7268</ul> 7269</div> 7270</div> 7271<div class="sect3"> 7272<h4 id="local_shared_ptr_pointer_constructor">pointer constructor</h4> 7273<div class="listingblock"> 7274<div class="content"> 7275<pre class="highlight"><code>template<class Y> explicit local_shared_ptr(Y * p);</code></pre> 7276</div> 7277</div> 7278<div class="ulist none"> 7279<ul class="none"> 7280<li> 7281<p></p> 7282<div class="dlist"> 7283<dl> 7284<dt class="hdlist1">Effects</dt> 7285<dd> 7286<p>Constructs a <code>local_shared_ptr</code> that owns <code>shared_ptr<T>( p )</code>.</p> 7287</dd> 7288<dt class="hdlist1">Postconditions</dt> 7289<dd> 7290<p><code>local_use_count() == 1 && get() == p</code>.</p> 7291</dd> 7292<dt class="hdlist1">Throws</dt> 7293<dd> 7294<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 7295</dd> 7296</dl> 7297</div> 7298</li> 7299</ul> 7300</div> 7301</div> 7302<div class="sect3"> 7303<h4 id="local_shared_ptr_constructors_taking_a_deleter">constructors taking a deleter</h4> 7304<div class="listingblock"> 7305<div class="content"> 7306<pre class="highlight"><code>template<class Y, class D> local_shared_ptr(Y * p, D d);</code></pre> 7307</div> 7308</div> 7309<div class="listingblock"> 7310<div class="content"> 7311<pre class="highlight"><code>template<class D> local_shared_ptr(std::nullptr_t p, D d);</code></pre> 7312</div> 7313</div> 7314<div class="ulist none"> 7315<ul class="none"> 7316<li> 7317<p></p> 7318<div class="dlist"> 7319<dl> 7320<dt class="hdlist1">Effects</dt> 7321<dd> 7322<p>Constructs a <code>local_shared_ptr</code> that owns <code>shared_ptr<T>( p, d )</code>.</p> 7323</dd> 7324<dt class="hdlist1">Postconditions</dt> 7325<dd> 7326<p><code>local_use_count() == 1 && get() == p</code>.</p> 7327</dd> 7328<dt class="hdlist1">Throws</dt> 7329<dd> 7330<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 7331</dd> 7332</dl> 7333</div> 7334</li> 7335</ul> 7336</div> 7337<div class="listingblock"> 7338<div class="content"> 7339<pre class="highlight"><code>template<class Y, class D, class A> local_shared_ptr(Y * p, D d, A a);</code></pre> 7340</div> 7341</div> 7342<div class="listingblock"> 7343<div class="content"> 7344<pre class="highlight"><code>template<class D, class A> local_shared_ptr(std::nullptr_t p, D d, A a);</code></pre> 7345</div> 7346</div> 7347<div class="ulist none"> 7348<ul class="none"> 7349<li> 7350<p></p> 7351<div class="dlist"> 7352<dl> 7353<dt class="hdlist1">Effects</dt> 7354<dd> 7355<p>Constructs a <code>local_shared_ptr</code> that owns <code>shared_ptr<T>( p, d, a )</code>.</p> 7356</dd> 7357<dt class="hdlist1">Postconditions</dt> 7358<dd> 7359<p><code>local_use_count() == 1 && get() == p</code>.</p> 7360</dd> 7361<dt class="hdlist1">Throws</dt> 7362<dd> 7363<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 7364</dd> 7365</dl> 7366</div> 7367</li> 7368</ul> 7369</div> 7370</div> 7371<div class="sect3"> 7372<h4 id="local_shared_ptr_copy_and_converting_constructors">copy and converting constructors</h4> 7373<div class="listingblock"> 7374<div class="content"> 7375<pre class="highlight"><code>local_shared_ptr(local_shared_ptr const & r) noexcept;</code></pre> 7376</div> 7377</div> 7378<div class="listingblock"> 7379<div class="content"> 7380<pre class="highlight"><code>template<class Y> local_shared_ptr(local_shared_ptr<Y> const & r) noexcept;</code></pre> 7381</div> 7382</div> 7383<div class="ulist none"> 7384<ul class="none"> 7385<li> 7386<p></p> 7387<div class="dlist"> 7388<dl> 7389<dt class="hdlist1">Requires</dt> 7390<dd> 7391<p><code>Y*</code> should be convertible to <code>T*</code>.</p> 7392</dd> 7393<dt class="hdlist1">Effects</dt> 7394<dd> 7395<p>If <code>r</code> is empty, constructs an empty <code>local_shared_ptr</code>; otherwise, constructs a <code>local_shared_ptr</code> that shares ownership with <code>r</code>.</p> 7396</dd> 7397<dt class="hdlist1">Postconditions</dt> 7398<dd> 7399<p><code>get() == r.get() && local_use_count() == r.local_use_count()</code>.</p> 7400</dd> 7401</dl> 7402</div> 7403</li> 7404</ul> 7405</div> 7406</div> 7407<div class="sect3"> 7408<h4 id="local_shared_ptr_move_constructors">move constructors</h4> 7409<div class="listingblock"> 7410<div class="content"> 7411<pre class="highlight"><code>local_shared_ptr(local_shared_ptr && r) noexcept;</code></pre> 7412</div> 7413</div> 7414<div class="listingblock"> 7415<div class="content"> 7416<pre class="highlight"><code>template<class Y> local_shared_ptr(local_shared_ptr<Y> && r) noexcept;</code></pre> 7417</div> 7418</div> 7419<div class="ulist none"> 7420<ul class="none"> 7421<li> 7422<p></p> 7423<div class="dlist"> 7424<dl> 7425<dt class="hdlist1">Requires</dt> 7426<dd> 7427<p><code>Y*</code> should be convertible to <code>T*</code>.</p> 7428</dd> 7429<dt class="hdlist1">Effects</dt> 7430<dd> 7431<p>Move-constructs a <code>local_shared_ptr</code> from <code>r</code>.</p> 7432</dd> 7433<dt class="hdlist1">Postconditions</dt> 7434<dd> 7435<p><code>*this</code> contains the old value of <code>r</code>. <code>r</code> is empty and <code>r.get() == 0</code>.</p> 7436</dd> 7437</dl> 7438</div> 7439</li> 7440</ul> 7441</div> 7442</div> 7443<div class="sect3"> 7444<h4 id="local_shared_ptr_shared_ptr_constructor">shared_ptr constructor</h4> 7445<div class="listingblock"> 7446<div class="content"> 7447<pre class="highlight"><code>template<class Y> local_shared_ptr( shared_ptr<Y> const & r );</code></pre> 7448</div> 7449</div> 7450<div class="listingblock"> 7451<div class="content"> 7452<pre class="highlight"><code>template<class Y> local_shared_ptr( shared_ptr<Y> && r );</code></pre> 7453</div> 7454</div> 7455<div class="ulist none"> 7456<ul class="none"> 7457<li> 7458<p></p> 7459<div class="dlist"> 7460<dl> 7461<dt class="hdlist1">Effects</dt> 7462<dd> 7463<p>Constructs a <code>local_shared_ptr</code> that owns <code>r</code>.</p> 7464</dd> 7465<dt class="hdlist1">Postconditions</dt> 7466<dd> 7467<p><code>local_use_count() == 1</code>. <code>get()</code> returns the old value of <code>r.get()</code>.</p> 7468</dd> 7469<dt class="hdlist1">Throws</dt> 7470<dd> 7471<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 7472</dd> 7473</dl> 7474</div> 7475</li> 7476</ul> 7477</div> 7478</div> 7479<div class="sect3"> 7480<h4 id="local_shared_ptr_aliasing_constructor">aliasing constructor</h4> 7481<div class="listingblock"> 7482<div class="content"> 7483<pre class="highlight"><code>template<class Y> local_shared_ptr(local_shared_ptr<Y> const & r, element_type * p) noexcept;</code></pre> 7484</div> 7485</div> 7486<div class="ulist none"> 7487<ul class="none"> 7488<li> 7489<p></p> 7490<div class="dlist"> 7491<dl> 7492<dt class="hdlist1">Effects</dt> 7493<dd> 7494<p>constructs a <code>local_shared_ptr</code> that shares ownership with <code>r</code> and stores <code>p</code>.</p> 7495</dd> 7496<dt class="hdlist1">Postconditions</dt> 7497<dd> 7498<p><code>get() == p && local_use_count() == r.local_use_count()</code>.</p> 7499</dd> 7500</dl> 7501</div> 7502</li> 7503</ul> 7504</div> 7505</div> 7506<div class="sect3"> 7507<h4 id="local_shared_ptr_aliasing_move_constructor">aliasing move constructor</h4> 7508<div class="listingblock"> 7509<div class="content"> 7510<pre class="highlight"><code>template<class Y> local_shared_ptr(local_shared_ptr<Y> && r, element_type * p) noexcept;</code></pre> 7511</div> 7512</div> 7513<div class="ulist none"> 7514<ul class="none"> 7515<li> 7516<p></p> 7517<div class="dlist"> 7518<dl> 7519<dt class="hdlist1">Effects</dt> 7520<dd> 7521<p>Move-constructs a <code>local_shared_ptr</code> from <code>r</code>, while storing <code>p</code> instead.</p> 7522</dd> 7523<dt class="hdlist1">Postconditions</dt> 7524<dd> 7525<p><code>get() == p</code> and <code>local_use_count()</code> equals the old count of <code>r</code>. <code>r</code> is empty and <code>r.get() == 0</code>.</p> 7526</dd> 7527</dl> 7528</div> 7529</li> 7530</ul> 7531</div> 7532</div> 7533<div class="sect3"> 7534<h4 id="local_shared_ptr_unique_ptr_constructor">unique_ptr constructor</h4> 7535<div class="listingblock"> 7536<div class="content"> 7537<pre class="highlight"><code>template<class Y, class D> local_shared_ptr(std::unique_ptr<Y, D> && r);</code></pre> 7538</div> 7539</div> 7540<div class="ulist none"> 7541<ul class="none"> 7542<li> 7543<p></p> 7544<div class="dlist"> 7545<dl> 7546<dt class="hdlist1">Requires</dt> 7547<dd> 7548<p><code>Y*</code> should be convertible to <code>T*</code>.</p> 7549</dd> 7550<dt class="hdlist1">Effects</dt> 7551<dd> 7552<div class="ulist"> 7553<ul> 7554<li> 7555<p>When <code>r.get() == 0</code>, equivalent to <code>local_shared_ptr()</code>;</p> 7556</li> 7557<li> 7558<p>Otherwise, constructs a <code>local_shared_ptr</code> that owns <code>shared_ptr<T>( std::move(r) )</code>.</p> 7559</li> 7560</ul> 7561</div> 7562</dd> 7563<dt class="hdlist1">Throws</dt> 7564<dd> 7565<p><code>std::bad_alloc</code>, or an implementation-defined exception when a resource other than memory could not be obtained.</p> 7566</dd> 7567<dt class="hdlist1">Exception safety</dt> 7568<dd> 7569<p>If an exception is thrown, the constructor has no effect.</p> 7570</dd> 7571</dl> 7572</div> 7573</li> 7574</ul> 7575</div> 7576</div> 7577<div class="sect3"> 7578<h4 id="local_shared_ptr_destructor">destructor</h4> 7579<div class="listingblock"> 7580<div class="content"> 7581<pre class="highlight"><code>~local_shared_ptr() noexcept;</code></pre> 7582</div> 7583</div> 7584<div class="ulist none"> 7585<ul class="none"> 7586<li> 7587<p></p> 7588<div class="dlist"> 7589<dl> 7590<dt class="hdlist1">Effects</dt> 7591<dd> 7592<div class="ulist"> 7593<ul> 7594<li> 7595<p>If <code>*this</code> is empty, or shares ownership with another <code>local_shared_ptr</code> instance (<code>local_use_count() > 1</code>), there are no side effects.</p> 7596</li> 7597<li> 7598<p>Otherwise, destroys the owned <code>shared_ptr</code>.</p> 7599</li> 7600</ul> 7601</div> 7602</dd> 7603</dl> 7604</div> 7605</li> 7606</ul> 7607</div> 7608</div> 7609<div class="sect3"> 7610<h4 id="local_shared_ptr_assignment">assignment</h4> 7611<div class="listingblock"> 7612<div class="content"> 7613<pre class="highlight"><code>local_shared_ptr & operator=(local_shared_ptr const & r) noexcept;</code></pre> 7614</div> 7615</div> 7616<div class="listingblock"> 7617<div class="content"> 7618<pre class="highlight"><code>template<class Y> local_shared_ptr & operator=(local_shared_ptr<Y> const & r) noexcept;</code></pre> 7619</div> 7620</div> 7621<div class="ulist none"> 7622<ul class="none"> 7623<li> 7624<p></p> 7625<div class="dlist"> 7626<dl> 7627<dt class="hdlist1">Effects</dt> 7628<dd> 7629<p>Equivalent to <code>local_shared_ptr(r).swap(*this)</code>.</p> 7630</dd> 7631<dt class="hdlist1">Returns</dt> 7632<dd> 7633<p><code>*this</code>.</p> 7634</dd> 7635</dl> 7636</div> 7637</li> 7638</ul> 7639</div> 7640<div class="listingblock"> 7641<div class="content"> 7642<pre class="highlight"><code>local_shared_ptr & operator=(local_shared_ptr && r) noexcept;</code></pre> 7643</div> 7644</div> 7645<div class="listingblock"> 7646<div class="content"> 7647<pre class="highlight"><code>template<class Y> local_shared_ptr & operator=(local_shared_ptr<Y> && r) noexcept;</code></pre> 7648</div> 7649</div> 7650<div class="listingblock"> 7651<div class="content"> 7652<pre class="highlight"><code>template<class Y, class D> local_shared_ptr & operator=(std::unique_ptr<Y, D> && r);</code></pre> 7653</div> 7654</div> 7655<div class="ulist none"> 7656<ul class="none"> 7657<li> 7658<p></p> 7659<div class="dlist"> 7660<dl> 7661<dt class="hdlist1">Effects</dt> 7662<dd> 7663<p>Equivalent to <code>local_shared_ptr(std::move(r)).swap(*this)</code>.</p> 7664</dd> 7665<dt class="hdlist1">Returns</dt> 7666<dd> 7667<p><code>*this</code>.</p> 7668</dd> 7669</dl> 7670</div> 7671</li> 7672</ul> 7673</div> 7674<div class="listingblock"> 7675<div class="content"> 7676<pre class="highlight"><code>local_shared_ptr & operator=(std::nullptr_t) noexcept;</code></pre> 7677</div> 7678</div> 7679<div class="ulist none"> 7680<ul class="none"> 7681<li> 7682<p></p> 7683<div class="dlist"> 7684<dl> 7685<dt class="hdlist1">Effects</dt> 7686<dd> 7687<p>Equivalent to <code>local_shared_ptr().swap(*this)</code>.</p> 7688</dd> 7689<dt class="hdlist1">Returns</dt> 7690<dd> 7691<p><code>*this</code>.</p> 7692</dd> 7693</dl> 7694</div> 7695</li> 7696</ul> 7697</div> 7698</div> 7699<div class="sect3"> 7700<h4 id="local_shared_ptr_reset">reset</h4> 7701<div class="listingblock"> 7702<div class="content"> 7703<pre class="highlight"><code>void reset() noexcept;</code></pre> 7704</div> 7705</div> 7706<div class="ulist none"> 7707<ul class="none"> 7708<li> 7709<p></p> 7710<div class="dlist"> 7711<dl> 7712<dt class="hdlist1">Effects</dt> 7713<dd> 7714<p>Equivalent to <code>local_shared_ptr().swap(*this)</code>.</p> 7715</dd> 7716</dl> 7717</div> 7718</li> 7719</ul> 7720</div> 7721<div class="listingblock"> 7722<div class="content"> 7723<pre class="highlight"><code>template<class Y> void reset(Y * p);</code></pre> 7724</div> 7725</div> 7726<div class="ulist none"> 7727<ul class="none"> 7728<li> 7729<p></p> 7730<div class="dlist"> 7731<dl> 7732<dt class="hdlist1">Effects</dt> 7733<dd> 7734<p>Equivalent to <code>local_shared_ptr(p).swap(*this)</code>.</p> 7735</dd> 7736</dl> 7737</div> 7738</li> 7739</ul> 7740</div> 7741<div class="listingblock"> 7742<div class="content"> 7743<pre class="highlight"><code>template<class Y, class D> void reset(Y * p, D d);</code></pre> 7744</div> 7745</div> 7746<div class="ulist none"> 7747<ul class="none"> 7748<li> 7749<p></p> 7750<div class="dlist"> 7751<dl> 7752<dt class="hdlist1">Effects</dt> 7753<dd> 7754<p>Equivalent to <code>local_shared_ptr(p, d).swap(*this)</code>.</p> 7755</dd> 7756</dl> 7757</div> 7758</li> 7759</ul> 7760</div> 7761<div class="listingblock"> 7762<div class="content"> 7763<pre class="highlight"><code>template<class Y, class D, class A> void reset(Y * p, D d, A a);</code></pre> 7764</div> 7765</div> 7766<div class="ulist none"> 7767<ul class="none"> 7768<li> 7769<p></p> 7770<div class="dlist"> 7771<dl> 7772<dt class="hdlist1">Effects</dt> 7773<dd> 7774<p>Equivalent to <code>local_shared_ptr(p, d, a).swap(*this)</code>.</p> 7775</dd> 7776</dl> 7777</div> 7778</li> 7779</ul> 7780</div> 7781<div class="listingblock"> 7782<div class="content"> 7783<pre class="highlight"><code>template<class Y> void reset(local_shared_ptr<Y> const & r, element_type * p) noexcept;</code></pre> 7784</div> 7785</div> 7786<div class="ulist none"> 7787<ul class="none"> 7788<li> 7789<p></p> 7790<div class="dlist"> 7791<dl> 7792<dt class="hdlist1">Effects</dt> 7793<dd> 7794<p>Equivalent to <code>local_shared_ptr(r, p).swap(*this)</code>.</p> 7795</dd> 7796</dl> 7797</div> 7798</li> 7799</ul> 7800</div> 7801<div class="listingblock"> 7802<div class="content"> 7803<pre class="highlight"><code>template<class Y> void reset(local_shared_ptr<Y> && r, element_type * p) noexcept;</code></pre> 7804</div> 7805</div> 7806<div class="ulist none"> 7807<ul class="none"> 7808<li> 7809<p></p> 7810<div class="dlist"> 7811<dl> 7812<dt class="hdlist1">Effects</dt> 7813<dd> 7814<p>Equivalent to <code>local_shared_ptr(std::move(r), p).swap(*this)</code>.</p> 7815</dd> 7816</dl> 7817</div> 7818</li> 7819</ul> 7820</div> 7821</div> 7822<div class="sect3"> 7823<h4 id="local_shared_ptr_indirection">indirection</h4> 7824<div class="listingblock"> 7825<div class="content"> 7826<pre class="highlight"><code>T & operator*() const noexcept;</code></pre> 7827</div> 7828</div> 7829<div class="ulist none"> 7830<ul class="none"> 7831<li> 7832<p></p> 7833<div class="dlist"> 7834<dl> 7835<dt class="hdlist1">Requires</dt> 7836<dd> 7837<p><code>T</code> should not be an array type.</p> 7838</dd> 7839<dt class="hdlist1">Returns</dt> 7840<dd> 7841<p><code>*get()</code>.</p> 7842</dd> 7843</dl> 7844</div> 7845</li> 7846</ul> 7847</div> 7848<div class="listingblock"> 7849<div class="content"> 7850<pre class="highlight"><code>T * operator->() const noexcept;</code></pre> 7851</div> 7852</div> 7853<div class="ulist none"> 7854<ul class="none"> 7855<li> 7856<p></p> 7857<div class="dlist"> 7858<dl> 7859<dt class="hdlist1">Requires</dt> 7860<dd> 7861<p><code>T</code> should not be an array type.</p> 7862</dd> 7863<dt class="hdlist1">Returns</dt> 7864<dd> 7865<p><code>get()</code>.</p> 7866</dd> 7867</dl> 7868</div> 7869</li> 7870</ul> 7871</div> 7872<div class="listingblock"> 7873<div class="content"> 7874<pre class="highlight"><code>element_type & operator[](std::ptrdiff_t i) const noexcept;</code></pre> 7875</div> 7876</div> 7877<div class="ulist none"> 7878<ul class="none"> 7879<li> 7880<p></p> 7881<div class="dlist"> 7882<dl> 7883<dt class="hdlist1">Requires</dt> 7884<dd> 7885<p><code>T</code> should be an array type. The stored pointer must not be 0. <code>i >= 0</code>. If <code>T</code> is <code>U[N]</code>, <code>i < N</code>.</p> 7886</dd> 7887<dt class="hdlist1">Returns</dt> 7888<dd> 7889<p><code>get()[i]</code>.</p> 7890</dd> 7891</dl> 7892</div> 7893</li> 7894</ul> 7895</div> 7896</div> 7897<div class="sect3"> 7898<h4 id="local_shared_ptr_get">get</h4> 7899<div class="listingblock"> 7900<div class="content"> 7901<pre class="highlight"><code>element_type * get() const noexcept;</code></pre> 7902</div> 7903</div> 7904<div class="ulist none"> 7905<ul class="none"> 7906<li> 7907<p></p> 7908<div class="dlist"> 7909<dl> 7910<dt class="hdlist1">Returns</dt> 7911<dd> 7912<p>The stored pointer.</p> 7913</dd> 7914</dl> 7915</div> 7916</li> 7917</ul> 7918</div> 7919</div> 7920<div class="sect3"> 7921<h4 id="local_shared_ptr_local_use_count">local_use_count</h4> 7922<div class="listingblock"> 7923<div class="content"> 7924<pre class="highlight"><code>long local_use_count() const noexcept;</code></pre> 7925</div> 7926</div> 7927<div class="ulist none"> 7928<ul class="none"> 7929<li> 7930<p></p> 7931<div class="dlist"> 7932<dl> 7933<dt class="hdlist1">Returns</dt> 7934<dd> 7935<p>The number of <code>local_shared_ptr</code> objects, <code>*this</code> included, that share ownership with <code>*this</code>, or 0 when <code>*this</code> is empty.</p> 7936</dd> 7937</dl> 7938</div> 7939</li> 7940</ul> 7941</div> 7942</div> 7943<div class="sect3"> 7944<h4 id="local_shared_ptr_conversions">conversions</h4> 7945<div class="listingblock"> 7946<div class="content"> 7947<pre class="highlight"><code>explicit operator bool() const noexcept;</code></pre> 7948</div> 7949</div> 7950<div class="ulist none"> 7951<ul class="none"> 7952<li> 7953<p></p> 7954<div class="dlist"> 7955<dl> 7956<dt class="hdlist1">Returns</dt> 7957<dd> 7958<p><code>get() != 0</code>.</p> 7959</dd> 7960</dl> 7961</div> 7962</li> 7963</ul> 7964</div> 7965<div class="admonitionblock note"> 7966<table> 7967<tr> 7968<td class="icon"> 7969<div class="title">Note</div> 7970</td> 7971<td class="content"> 7972On C++03 compilers, the return value is of an unspecified type. 7973</td> 7974</tr> 7975</table> 7976</div> 7977<div class="listingblock"> 7978<div class="content"> 7979<pre class="highlight"><code>template<class Y> operator shared_ptr<Y>() const noexcept;</code></pre> 7980</div> 7981</div> 7982<div class="listingblock"> 7983<div class="content"> 7984<pre class="highlight"><code>template<class Y> operator weak_ptr<Y>() const noexcept;</code></pre> 7985</div> 7986</div> 7987<div class="ulist none"> 7988<ul class="none"> 7989<li> 7990<p></p> 7991<div class="dlist"> 7992<dl> 7993<dt class="hdlist1">Requires</dt> 7994<dd> 7995<p><code>T*</code> should be convertible to <code>Y*</code>.</p> 7996</dd> 7997<dt class="hdlist1">Returns</dt> 7998<dd> 7999<p>a copy of the owned <code>shared_ptr</code>.</p> 8000</dd> 8001</dl> 8002</div> 8003</li> 8004</ul> 8005</div> 8006</div> 8007<div class="sect3"> 8008<h4 id="local_shared_ptr_swap">swap</h4> 8009<div class="listingblock"> 8010<div class="content"> 8011<pre class="highlight"><code>void swap(local_shared_ptr & b) noexcept;</code></pre> 8012</div> 8013</div> 8014<div class="ulist none"> 8015<ul class="none"> 8016<li> 8017<p></p> 8018<div class="dlist"> 8019<dl> 8020<dt class="hdlist1">Effects</dt> 8021<dd> 8022<p>Exchanges the contents of the two smart pointers.</p> 8023</dd> 8024</dl> 8025</div> 8026</li> 8027</ul> 8028</div> 8029</div> 8030<div class="sect3"> 8031<h4 id="local_shared_ptr_owner_before">owner_before</h4> 8032<div class="listingblock"> 8033<div class="content"> 8034<pre class="highlight"><code>template<class Y> bool owner_before(local_shared_ptr<Y> const & r) const noexcept;</code></pre> 8035</div> 8036</div> 8037<div class="ulist none"> 8038<ul class="none"> 8039<li> 8040<p></p> 8041<div class="dlist"> 8042<dl> 8043<dt class="hdlist1">Returns</dt> 8044<dd> 8045<p>See the description of <code>operator<</code>.</p> 8046</dd> 8047</dl> 8048</div> 8049</li> 8050</ul> 8051</div> 8052</div> 8053<div class="sect3"> 8054<h4 id="local_shared_ptr_owner_equals">owner_equals</h4> 8055<div class="listingblock"> 8056<div class="content"> 8057<pre class="highlight"><code>template<class Y> bool owner_equals(local_shared_ptr<Y> const & r) const noexcept;</code></pre> 8058</div> 8059</div> 8060<div class="ulist none"> 8061<ul class="none"> 8062<li> 8063<p></p> 8064<div class="dlist"> 8065<dl> 8066<dt class="hdlist1">Returns</dt> 8067<dd> 8068<p><code>true</code> if and only if <code>*this</code> and <code>r</code> share ownership or are both empty.</p> 8069</dd> 8070</dl> 8071</div> 8072</li> 8073</ul> 8074</div> 8075</div> 8076</div> 8077<div class="sect2"> 8078<h3 id="local_shared_ptr_free_functions">Free Functions</h3> 8079<div class="sect3"> 8080<h4 id="local_shared_ptr_comparison">comparison</h4> 8081<div class="listingblock"> 8082<div class="content"> 8083<pre class="highlight"><code>template<class T, class U> 8084 bool operator==(local_shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept;</code></pre> 8085</div> 8086</div> 8087<div class="listingblock"> 8088<div class="content"> 8089<pre class="highlight"><code>template<class T, class U> 8090 bool operator==(local_shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept;</code></pre> 8091</div> 8092</div> 8093<div class="listingblock"> 8094<div class="content"> 8095<pre class="highlight"><code>template<class T, class U> 8096 bool operator==(shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept;</code></pre> 8097</div> 8098</div> 8099<div class="ulist none"> 8100<ul class="none"> 8101<li> 8102<p></p> 8103<div class="dlist"> 8104<dl> 8105<dt class="hdlist1">Returns</dt> 8106<dd> 8107<p><code>a.get() == b.get()</code>.</p> 8108</dd> 8109</dl> 8110</div> 8111</li> 8112</ul> 8113</div> 8114<div class="listingblock"> 8115<div class="content"> 8116<pre class="highlight"><code>template<class T, class U> 8117 bool operator!=(local_shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept;</code></pre> 8118</div> 8119</div> 8120<div class="listingblock"> 8121<div class="content"> 8122<pre class="highlight"><code>template<class T, class U> 8123 bool operator!=(local_shared_ptr<T> const & a, shared_ptr<U> const & b) noexcept;</code></pre> 8124</div> 8125</div> 8126<div class="listingblock"> 8127<div class="content"> 8128<pre class="highlight"><code>template<class T, class U> 8129 bool operator!=(shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept;</code></pre> 8130</div> 8131</div> 8132<div class="ulist none"> 8133<ul class="none"> 8134<li> 8135<p></p> 8136<div class="dlist"> 8137<dl> 8138<dt class="hdlist1">Returns</dt> 8139<dd> 8140<p><code>a.get() != b.get()</code>.</p> 8141</dd> 8142</dl> 8143</div> 8144</li> 8145</ul> 8146</div> 8147<div class="listingblock"> 8148<div class="content"> 8149<pre class="highlight"><code>template<class T> bool operator==(local_shared_ptr<T> const & p, std::nullptr_t) noexcept;</code></pre> 8150</div> 8151</div> 8152<div class="listingblock"> 8153<div class="content"> 8154<pre class="highlight"><code>template<class T> bool operator==(std::nullptr_t, local_shared_ptr<T> const & p) noexcept;</code></pre> 8155</div> 8156</div> 8157<div class="ulist none"> 8158<ul class="none"> 8159<li> 8160<p></p> 8161<div class="dlist"> 8162<dl> 8163<dt class="hdlist1">Returns</dt> 8164<dd> 8165<p><code>p.get() == 0</code>.</p> 8166</dd> 8167</dl> 8168</div> 8169</li> 8170</ul> 8171</div> 8172<div class="listingblock"> 8173<div class="content"> 8174<pre class="highlight"><code>template<class T> bool operator!=(local_shared_ptr<T> const & p, std::nullptr_t) noexcept;</code></pre> 8175</div> 8176</div> 8177<div class="listingblock"> 8178<div class="content"> 8179<pre class="highlight"><code>template<class T> bool operator!=(std::nullptr_t, local_shared_ptr<T> const & p) noexcept;</code></pre> 8180</div> 8181</div> 8182<div class="ulist none"> 8183<ul class="none"> 8184<li> 8185<p></p> 8186<div class="dlist"> 8187<dl> 8188<dt class="hdlist1">Returns</dt> 8189<dd> 8190<p><code>p.get() != 0</code>.</p> 8191</dd> 8192</dl> 8193</div> 8194</li> 8195</ul> 8196</div> 8197<div class="listingblock"> 8198<div class="content"> 8199<pre class="highlight"><code>template<class T, class U> 8200 bool operator<(local_shared_ptr<T> const & a, local_shared_ptr<U> const & b) noexcept;</code></pre> 8201</div> 8202</div> 8203<div class="ulist none"> 8204<ul class="none"> 8205<li> 8206<p></p> 8207<div class="dlist"> 8208<dl> 8209<dt class="hdlist1">Returns</dt> 8210<dd> 8211<p>An unspecified value such that</p> 8212<div class="ulist"> 8213<ul> 8214<li> 8215<p><code>operator<</code> is a strict weak ordering as described in section [lib.alg.sorting] of the C++ standard;</p> 8216</li> 8217<li> 8218<p>under the equivalence relation defined by <code>operator<</code>, <code>!(a < b) && !(b < a)</code>, two <code>local_shared_ptr</code> instances 8219are equivalent if and only if they share ownership or are both empty.</p> 8220</li> 8221</ul> 8222</div> 8223</dd> 8224</dl> 8225</div> 8226</li> 8227</ul> 8228</div> 8229<div class="admonitionblock note"> 8230<table> 8231<tr> 8232<td class="icon"> 8233<div class="title">Note</div> 8234</td> 8235<td class="content"> 8236Allows <code>local_shared_ptr</code> objects to be used as keys in associative containers. 8237</td> 8238</tr> 8239</table> 8240</div> 8241<div class="admonitionblock note"> 8242<table> 8243<tr> 8244<td class="icon"> 8245<div class="title">Note</div> 8246</td> 8247<td class="content"> 8248The rest of the comparison operators are omitted by design. 8249</td> 8250</tr> 8251</table> 8252</div> 8253</div> 8254<div class="sect3"> 8255<h4 id="local_shared_ptr_swap_2">swap</h4> 8256<div class="listingblock"> 8257<div class="content"> 8258<pre class="highlight"><code>template<class T> void swap(local_shared_ptr<T> & a, local_shared_ptr<T> & b) noexcept;</code></pre> 8259</div> 8260</div> 8261<div class="ulist none"> 8262<ul class="none"> 8263<li> 8264<p></p> 8265<div class="dlist"> 8266<dl> 8267<dt class="hdlist1">Effects</dt> 8268<dd> 8269<p>Equivalent to <code>a.swap(b)</code>.</p> 8270</dd> 8271</dl> 8272</div> 8273</li> 8274</ul> 8275</div> 8276</div> 8277<div class="sect3"> 8278<h4 id="local_shared_ptr_get_pointer">get_pointer</h4> 8279<div class="listingblock"> 8280<div class="content"> 8281<pre class="highlight"><code>template<class T> 8282 typename local_shared_ptr<T>::element_type * 8283 get_pointer(local_shared_ptr<T> const & p) noexcept;</code></pre> 8284</div> 8285</div> 8286<div class="ulist none"> 8287<ul class="none"> 8288<li> 8289<p></p> 8290<div class="dlist"> 8291<dl> 8292<dt class="hdlist1">Returns</dt> 8293<dd> 8294<p><code>p.get()</code>.</p> 8295</dd> 8296</dl> 8297</div> 8298</li> 8299</ul> 8300</div> 8301<div class="admonitionblock note"> 8302<table> 8303<tr> 8304<td class="icon"> 8305<div class="title">Note</div> 8306</td> 8307<td class="content"> 8308Provided as an aid to generic programming. Used by <code>mem_fn</code>. 8309</td> 8310</tr> 8311</table> 8312</div> 8313</div> 8314<div class="sect3"> 8315<h4 id="local_shared_ptr_static_pointer_cast">static_pointer_cast</h4> 8316<div class="listingblock"> 8317<div class="content"> 8318<pre class="highlight"><code>template<class T, class U> 8319 local_shared_ptr<T> static_pointer_cast(local_shared_ptr<U> const & r) noexcept;</code></pre> 8320</div> 8321</div> 8322<div class="ulist none"> 8323<ul class="none"> 8324<li> 8325<p></p> 8326<div class="dlist"> 8327<dl> 8328<dt class="hdlist1">Requires</dt> 8329<dd> 8330<p>The expression <code>static_cast<T*>( (U*)0 )</code> must be well-formed.</p> 8331</dd> 8332<dt class="hdlist1">Returns</dt> 8333<dd> 8334<p><code>local_shared_ptr<T>( r, static_cast<typename local_shared_ptr<T>::element_type*>(r.get()) )</code>.</p> 8335</dd> 8336</dl> 8337</div> 8338</li> 8339</ul> 8340</div> 8341<div class="admonitionblock caution"> 8342<table> 8343<tr> 8344<td class="icon"> 8345<div class="title">Caution</div> 8346</td> 8347<td class="content"> 8348The seemingly equivalent expression <code>local_shared_ptr<T>(static_cast<T*>(r.get()))</code> will eventually 8349result in undefined behavior, attempting to delete the same object twice. 8350</td> 8351</tr> 8352</table> 8353</div> 8354</div> 8355<div class="sect3"> 8356<h4 id="local_shared_ptr_const_pointer_cast">const_pointer_cast</h4> 8357<div class="listingblock"> 8358<div class="content"> 8359<pre class="highlight"><code>template<class T, class U> 8360 local_shared_ptr<T> const_pointer_cast(local_shared_ptr<U> const & r) noexcept;</code></pre> 8361</div> 8362</div> 8363<div class="ulist none"> 8364<ul class="none"> 8365<li> 8366<p></p> 8367<div class="dlist"> 8368<dl> 8369<dt class="hdlist1">Requires</dt> 8370<dd> 8371<p>The expression <code>const_cast<T*>( (U*)0 )</code> must be well-formed.</p> 8372</dd> 8373<dt class="hdlist1">Returns</dt> 8374<dd> 8375<p><code>local_shared_ptr<T>( r, const_cast<typename local_shared_ptr<T>::element_type*>(r.get()) )</code>.</p> 8376</dd> 8377</dl> 8378</div> 8379</li> 8380</ul> 8381</div> 8382</div> 8383<div class="sect3"> 8384<h4 id="local_shared_ptr_dynamic_pointer_cast">dynamic_pointer_cast</h4> 8385<div class="listingblock"> 8386<div class="content"> 8387<pre class="highlight"><code>template<class T, class U> 8388 local_shared_ptr<T> dynamic_pointer_cast(local_shared_ptr<U> const & r) noexcept;</code></pre> 8389</div> 8390</div> 8391<div class="ulist none"> 8392<ul class="none"> 8393<li> 8394<p></p> 8395<div class="dlist"> 8396<dl> 8397<dt class="hdlist1">Requires</dt> 8398<dd> 8399<p>The expression <code>dynamic_cast<T*>( (U*)0 )</code> must be well-formed.</p> 8400</dd> 8401<dt class="hdlist1">Returns</dt> 8402<dd> 8403<div class="ulist"> 8404<ul> 8405<li> 8406<p>When <code>dynamic_cast<typename local_shared_ptr<T>::element_type*>(r.get())</code> returns a nonzero value <code>p</code>, <code>local_shared_ptr<T>(r, p)</code>;</p> 8407</li> 8408<li> 8409<p>Otherwise, <code>local_shared_ptr<T>()</code>.</p> 8410</li> 8411</ul> 8412</div> 8413</dd> 8414</dl> 8415</div> 8416</li> 8417</ul> 8418</div> 8419</div> 8420<div class="sect3"> 8421<h4 id="local_shared_ptr_reinterpret_pointer_cast">reinterpret_pointer_cast</h4> 8422<div class="listingblock"> 8423<div class="content"> 8424<pre class="highlight"><code>template<class T, class U> 8425 local_shared_ptr<T> reinterpret_pointer_cast(local_shared_ptr<U> const & r) noexcept;</code></pre> 8426</div> 8427</div> 8428<div class="ulist none"> 8429<ul class="none"> 8430<li> 8431<p></p> 8432<div class="dlist"> 8433<dl> 8434<dt class="hdlist1">Requires</dt> 8435<dd> 8436<p>The expression <code>reinterpret_cast<T*>( (U*)0 )</code> must be well-formed.</p> 8437</dd> 8438<dt class="hdlist1">Returns</dt> 8439<dd> 8440<p><code>local_shared_ptr<T>( r, reinterpret_cast<typename local_shared_ptr<T>::element_type*>(r.get()) )</code>.</p> 8441</dd> 8442</dl> 8443</div> 8444</li> 8445</ul> 8446</div> 8447</div> 8448<div class="sect3"> 8449<h4 id="local_shared_ptr_operator">operator<<</h4> 8450<div class="listingblock"> 8451<div class="content"> 8452<pre class="highlight"><code>template<class E, class T, class Y> 8453 std::basic_ostream<E, T> & 8454 operator<< (std::basic_ostream<E, T> & os, local_shared_ptr<Y> const & p);</code></pre> 8455</div> 8456</div> 8457<div class="ulist none"> 8458<ul class="none"> 8459<li> 8460<p></p> 8461<div class="dlist"> 8462<dl> 8463<dt class="hdlist1">Effects</dt> 8464<dd> 8465<p><code>os << p.get();</code>.</p> 8466</dd> 8467<dt class="hdlist1">Returns</dt> 8468<dd> 8469<p><code>os</code>.</p> 8470</dd> 8471</dl> 8472</div> 8473</li> 8474</ul> 8475</div> 8476</div> 8477<div class="sect3"> 8478<h4 id="local_shared_ptr_get_deleter">get_deleter</h4> 8479<div class="listingblock"> 8480<div class="content"> 8481<pre class="highlight"><code>template<class D, class T> 8482 D * get_deleter(local_shared_ptr<T> const & p) noexcept;</code></pre> 8483</div> 8484</div> 8485<div class="ulist none"> 8486<ul class="none"> 8487<li> 8488<p></p> 8489<div class="dlist"> 8490<dl> 8491<dt class="hdlist1">Returns</dt> 8492<dd> 8493<p>If <code>*this</code> owns a <code>shared_ptr</code> instance <code>p</code>, <code>get_deleter<D>( p )</code>, otherwise 0.</p> 8494</dd> 8495</dl> 8496</div> 8497</li> 8498</ul> 8499</div> 8500</div> 8501</div> 8502</div> 8503</div> 8504<div class="sect1"> 8505<h2 id="make_local_shared">make_local_shared: Creating local_shared_ptr</h2> 8506<div class="sectionbody"> 8507<div class="sect2"> 8508<h3 id="make_local_shared_description">Description</h3> 8509<div class="paragraph"> 8510<p>The function templates <code>make_local_shared</code> and <code>allocate_local_shared</code> provide 8511convenient, safe and efficient ways to create <code>local_shared_ptr</code> objects. They 8512are analogous to <code>make_shared</code> and <code>allocate_shared</code> for <code>shared_ptr</code>.</p> 8513</div> 8514</div> 8515<div class="sect2"> 8516<h3 id="make_local_shared_synopsis">Synopsis</h3> 8517<div class="paragraph"> 8518<p><code>make_local_shared</code> and <code>allocate_local_shared</code> are defined in 8519<code><boost/smart_ptr/make_local_shared.hpp></code>.</p> 8520</div> 8521<div class="listingblock"> 8522<div class="content"> 8523<pre class="highlight"><code>namespace boost { 8524 <code>// T is not an array</code> 8525 template<class T, class... Args> 8526 local_shared_ptr<T> make_local_shared(Args&&... args); 8527 template<class T, class A, class... Args> 8528 local_shared_ptr<T> allocate_local_shared(const A& a, Args&&... args); 8529 8530 <code>// T is an array of unknown bounds</code> 8531 template<class T> 8532 local_shared_ptr<T> make_local_shared(std::size_t n); 8533 template<class T, class A> 8534 local_shared_ptr<T> allocate_local_shared(const A& a, std::size_t n); 8535 8536 <code>// T is an array of known bounds</code> 8537 template<class T> 8538 local_shared_ptr<T> make_local_shared(); 8539 template<class T, class A> 8540 local_shared_ptr<T> allocate_local_shared(const A& a); 8541 8542 <code>// T is an array of unknown bounds</code> 8543 template<class T> 8544 local_shared_ptr<T> make_local_shared(std::size_t n, 8545 const remove_extent_t<T>& v); 8546 template<class T, class A> 8547 local_shared_ptr<T> allocate_local_shared(const A& a, std::size_t n, 8548 const remove_extent_t<T>& v); 8549 8550 <code>// T is an array of known bounds</code> 8551 template<class T> 8552 local_shared_ptr<T> make_local_shared(const remove_extent_t<T>& v); 8553 template<class T, class A> 8554 local_shared_ptr<T> allocate_local_shared(const A& a, 8555 const remove_extent_t<T>& v); 8556 8557 <code>// T is not an array of known bounds</code> 8558 template<class T> 8559 local_shared_ptr<T> make_local_shared_noinit(); 8560 template<class T, class A> 8561 local_shared_ptr<T> allocate_local_shared_noinit(const A& a); 8562 8563 <code>// T is an array of unknown bounds</code> 8564 template<class T> 8565 local_shared_ptr<T> make_local_shared_noinit(std::size_t n); 8566 template<class T, class A> 8567 local_shared_ptr<T> allocate_local_shared_noinit(const A& a, 8568 std::size_t n); 8569}</code></pre> 8570</div> 8571</div> 8572</div> 8573<div class="sect2"> 8574<h3 id="make_local_shared_description_2">Description</h3> 8575<div class="paragraph"> 8576<p>The requirements and effects of these functions are the same as <code>make_shared</code> 8577and <code>allocate_shared</code>, except that a <code>local_shared_ptr</code> is returned.</p> 8578</div> 8579</div> 8580</div> 8581</div> 8582<div class="sect1"> 8583<h2 id="pointer_cast">Generic Pointer Casts</h2> 8584<div class="sectionbody"> 8585<div class="sect2"> 8586<h3 id="pointer_cast_description">Description</h3> 8587<div class="paragraph"> 8588<p>The pointer cast function templates (<code>static_pointer_cast</code>, 8589<code>dynamic_pointer_cast</code>, <code>const_pointer_cast</code>, and <code>reinterpret_pointer_cast</code>) 8590provide a way to write generic pointer castings for raw pointers, 8591<code>std::shared_ptr</code> and <code>std::unique_ptr</code>.</p> 8592</div> 8593<div class="paragraph"> 8594<p>There is test and example code in 8595<a href="../../test/pointer_cast_test.cpp">pointer_cast_test.cpp</a></p> 8596</div> 8597</div> 8598<div class="sect2"> 8599<h3 id="pointer_cast_rationale">Rationale</h3> 8600<div class="paragraph"> 8601<p>Boost smart pointers usually overload those functions to provide a mechanism 8602to emulate pointers casts. For example, <code>shared_ptr<T></code> implements a static 8603pointer cast this way:</p> 8604</div> 8605<div class="listingblock"> 8606<div class="content"> 8607<pre class="highlight"><code>template<class T, class U> 8608 shared_ptr<T> static_pointer_cast(const shared_ptr<U>& p);</code></pre> 8609</div> 8610</div> 8611<div class="paragraph"> 8612<p>Pointer cast functions templates are overloads of <code>static_pointer_cast</code>, 8613<code>dynamic_pointer_cast</code>, <code>const_pointer_cast</code>, and <code>reinterpret_pointer_cast</code> 8614for raw pointers, <code>std::shared_ptr</code> and <code>std::unique_ptr</code>. This way when 8615developing pointer type independent classes, for example, memory managers or 8616shared memory compatible classes, the same code can be used for raw and smart 8617pointers.</p> 8618</div> 8619</div> 8620<div class="sect2"> 8621<h3 id="pointer_cast_synopsis">Synopsis</h3> 8622<div class="paragraph"> 8623<p>The generic pointer casts are defined in <code><boost/pointer_cast.hpp></code>.</p> 8624</div> 8625<div class="listingblock"> 8626<div class="content"> 8627<pre class="highlight"><code>namespace boost { 8628 template<class T, class U> T* static_pointer_cast(U* p) noexcept; 8629 template<class T, class U> T* dynamic_pointer_cast(U* p) noexcept; 8630 template<class T, class U> T* const_pointer_cast(U* p) noexcept; 8631 template<class T, class U> T* reinterpret_pointer_cast(U* p) noexcept; 8632 8633 template<class T, class U> std::shared_ptr<T> 8634 static_pointer_cast(const std::shared_ptr<U>& p) noexcept; 8635 template<class T, class U> std::shared_ptr<T> 8636 dynamic_pointer_cast(const std::shared_ptr<U>& p) noexcept; 8637 template<class T, class U> std::shared_ptr<T> 8638 const_pointer_cast(const std::shared_ptr<U>& p) noexcept; 8639 template<class T, class U> std::shared_ptr<T> 8640 reinterpret_pointer_cast(const std::shared_ptr<U>& p) noexcept; 8641 8642 template<class T, class U> std::unique_ptr<T> 8643 static_pointer_cast(std::unique_ptr<U>&& p) noexcept; 8644 template<class T, class U> std::unique_ptr<T> 8645 dynamic_pointer_cast(std::unique_ptr<U>&& p) noexcept; 8646 template<class T, class U> std::unique_ptr<T> 8647 const_pointer_cast(std::unique_ptr<U>&& p) noexcept; 8648 template<class T, class U> std::unique_ptr<T> 8649 reinterpret_pointer_cast(std::unique_ptr<U>&& p) noexcept; 8650}</code></pre> 8651</div> 8652</div> 8653</div> 8654<div class="sect2"> 8655<h3 id="pointer_cast_free_functions">Free Functions</h3> 8656<div class="sect3"> 8657<h4 id="pointer_cast_static_pointer_cast">static_pointer_cast</h4> 8658<div class="listingblock"> 8659<div class="content"> 8660<pre class="highlight"><code>template<class T, class U> T* static_pointer_cast(U* p) noexcept;</code></pre> 8661</div> 8662</div> 8663<div class="ulist none"> 8664<ul class="none"> 8665<li> 8666<p></p> 8667<div class="dlist"> 8668<dl> 8669<dt class="hdlist1">Returns</dt> 8670<dd> 8671<p><code>static_cast<T*>(p)</code></p> 8672</dd> 8673</dl> 8674</div> 8675</li> 8676</ul> 8677</div> 8678<div class="listingblock"> 8679<div class="content"> 8680<pre class="highlight"><code>template<class T, class U> std::shared_ptr<T> 8681 static_pointer_cast(const std::shared_ptr<U>& p) noexcept;</code></pre> 8682</div> 8683</div> 8684<div class="ulist none"> 8685<ul class="none"> 8686<li> 8687<p></p> 8688<div class="dlist"> 8689<dl> 8690<dt class="hdlist1">Returns</dt> 8691<dd> 8692<p><code>std::static_pointer_cast<T>(p)</code></p> 8693</dd> 8694</dl> 8695</div> 8696</li> 8697</ul> 8698</div> 8699<div class="listingblock"> 8700<div class="content"> 8701<pre class="highlight"><code>template<class T, class U> std::unique_ptr<T> 8702 static_pointer_cast(std::unique_ptr<U>&& p) noexcept;</code></pre> 8703</div> 8704</div> 8705<div class="ulist none"> 8706<ul class="none"> 8707<li> 8708<p></p> 8709<div class="dlist"> 8710<dl> 8711<dt class="hdlist1">Requires</dt> 8712<dd> 8713<p>The expression <code>static_cast<T*>((U*)0)</code> must be well-formed.</p> 8714</dd> 8715<dt class="hdlist1">Returns</dt> 8716<dd> 8717<p><code>std::unique_ptr<T>(static_cast<typename 8718std::unique_ptr<T>::element_type*>(p.release()))</code>.</p> 8719</dd> 8720</dl> 8721</div> 8722</li> 8723</ul> 8724</div> 8725<div class="admonitionblock caution"> 8726<table> 8727<tr> 8728<td class="icon"> 8729<div class="title">Caution</div> 8730</td> 8731<td class="content"> 8732The seemingly equivalent expression 8733<code>std::unique_ptr<T>(static_cast<T*>(p.get()))</code> will eventually result in 8734undefined behavior, attempting to delete the same object twice. 8735</td> 8736</tr> 8737</table> 8738</div> 8739</div> 8740<div class="sect3"> 8741<h4 id="pointer_cast_dynamic_pointer_cast">dynamic_pointer_cast</h4> 8742<div class="listingblock"> 8743<div class="content"> 8744<pre class="highlight"><code>template<class T, class U> T* dynamic_pointer_cast(U* p) noexcept;</code></pre> 8745</div> 8746</div> 8747<div class="ulist none"> 8748<ul class="none"> 8749<li> 8750<p></p> 8751<div class="dlist"> 8752<dl> 8753<dt class="hdlist1">Returns</dt> 8754<dd> 8755<p><code>dynamic_cast<T*>(p)</code></p> 8756</dd> 8757</dl> 8758</div> 8759</li> 8760</ul> 8761</div> 8762<div class="listingblock"> 8763<div class="content"> 8764<pre class="highlight"><code>template<class T, class U> std::shared_ptr<T> 8765 dynamic_pointer_cast(const std::shared_ptr<U>& p) noexcept;</code></pre> 8766</div> 8767</div> 8768<div class="ulist none"> 8769<ul class="none"> 8770<li> 8771<p></p> 8772<div class="dlist"> 8773<dl> 8774<dt class="hdlist1">Returns</dt> 8775<dd> 8776<p><code>std::dynamic_pointer_cast<T>(p)</code></p> 8777</dd> 8778</dl> 8779</div> 8780</li> 8781</ul> 8782</div> 8783<div class="listingblock"> 8784<div class="content"> 8785<pre class="highlight"><code>template<class T, class U> std::unique_ptr<T> 8786 dynamic_pointer_cast(std::unique_ptr<U>&& p) noexcept;</code></pre> 8787</div> 8788</div> 8789<div class="ulist none"> 8790<ul class="none"> 8791<li> 8792<p></p> 8793<div class="dlist"> 8794<dl> 8795<dt class="hdlist1">Requires</dt> 8796</dl> 8797</div> 8798</li> 8799<li> 8800<p>The expression <code>static_cast<T*>((U*)0)</code> must be well-formed.</p> 8801</li> 8802<li> 8803<p><code>T</code> must have a virtual destructor.</p> 8804<div class="dlist"> 8805<dl> 8806<dt class="hdlist1">Returns</dt> 8807</dl> 8808</div> 8809</li> 8810<li> 8811<p>When <code>dynamic_cast<typename std::unique_ptr<T>::element_type*>(p.get())</code> 8812returns a non-zero value, <code>std::unique_ptr<T>(dynamic_cast<typename 8813std::unique_ptr<T>::element_type*>(p.release()));</code>.</p> 8814</li> 8815<li> 8816<p>Otherwise, <code>std::unique_ptr<T>()</code>.</p> 8817</li> 8818</ul> 8819</div> 8820</div> 8821<div class="sect3"> 8822<h4 id="pointer_cast_const_pointer_cast">const_pointer_cast</h4> 8823<div class="listingblock"> 8824<div class="content"> 8825<pre class="highlight"><code>template<class T, class U> T* const_pointer_cast(U* p) noexcept;</code></pre> 8826</div> 8827</div> 8828<div class="ulist none"> 8829<ul class="none"> 8830<li> 8831<p></p> 8832<div class="dlist"> 8833<dl> 8834<dt class="hdlist1">Returns</dt> 8835<dd> 8836<p><code>const_cast<T*>(p)</code></p> 8837</dd> 8838</dl> 8839</div> 8840</li> 8841</ul> 8842</div> 8843<div class="listingblock"> 8844<div class="content"> 8845<pre class="highlight"><code>template<class T, class U> std::shared_ptr<T> 8846 const_pointer_cast(const std::shared_ptr<U>& p) noexcept;</code></pre> 8847</div> 8848</div> 8849<div class="ulist none"> 8850<ul class="none"> 8851<li> 8852<p></p> 8853<div class="dlist"> 8854<dl> 8855<dt class="hdlist1">Returns</dt> 8856<dd> 8857<p><code>std::const_pointer_cast<T>(p)</code></p> 8858</dd> 8859</dl> 8860</div> 8861</li> 8862</ul> 8863</div> 8864<div class="listingblock"> 8865<div class="content"> 8866<pre class="highlight"><code>template<class T, class U> std::unique_ptr<T> 8867 const_pointer_cast(std::unique_ptr<U>&& p) noexcept;</code></pre> 8868</div> 8869</div> 8870<div class="ulist none"> 8871<ul class="none"> 8872<li> 8873<p></p> 8874<div class="dlist"> 8875<dl> 8876<dt class="hdlist1">Requires</dt> 8877<dd> 8878<p>The expression <code>const_cast<T*>((U*)0)</code> must be well-formed.</p> 8879</dd> 8880<dt class="hdlist1">Returns</dt> 8881<dd> 8882<p><code>std::unique_ptr<T>(const_cast<typename 8883std::unique_ptr<T>::element_type*>(p.release()))</code>.</p> 8884</dd> 8885</dl> 8886</div> 8887</li> 8888</ul> 8889</div> 8890</div> 8891<div class="sect3"> 8892<h4 id="pointer_cast_reinterpret_pointer_cast">reinterpret_pointer_cast</h4> 8893<div class="listingblock"> 8894<div class="content"> 8895<pre class="highlight"><code>template<class T, class U> T* reinterpret_pointer_cast(U* p) noexcept;</code></pre> 8896</div> 8897</div> 8898<div class="ulist none"> 8899<ul class="none"> 8900<li> 8901<p></p> 8902<div class="dlist"> 8903<dl> 8904<dt class="hdlist1">Returns</dt> 8905<dd> 8906<p><code>reinterpret_cast<T*>(p)</code></p> 8907</dd> 8908</dl> 8909</div> 8910</li> 8911</ul> 8912</div> 8913<div class="listingblock"> 8914<div class="content"> 8915<pre class="highlight"><code>template<class T, class U> std::shared_ptr<T> 8916 reinterpret_pointer_cast(const std::shared_ptr<U>& p) noexcept;</code></pre> 8917</div> 8918</div> 8919<div class="ulist none"> 8920<ul class="none"> 8921<li> 8922<p></p> 8923<div class="dlist"> 8924<dl> 8925<dt class="hdlist1">Returns</dt> 8926<dd> 8927<p><code>std::reinterpret_pointer_cast<T>(p)</code></p> 8928</dd> 8929</dl> 8930</div> 8931</li> 8932</ul> 8933</div> 8934<div class="listingblock"> 8935<div class="content"> 8936<pre class="highlight"><code>template<class T, class U> std::unique_ptr<T> 8937 reinterpret_pointer_cast(std::unique_ptr<U>&& p) noexcept;</code></pre> 8938</div> 8939</div> 8940<div class="ulist none"> 8941<ul class="none"> 8942<li> 8943<p></p> 8944<div class="dlist"> 8945<dl> 8946<dt class="hdlist1">Requires</dt> 8947<dd> 8948<p>The expression <code>reinterpret_cast<T*>((U*)0)</code> must be well-formed.</p> 8949</dd> 8950<dt class="hdlist1">Returns</dt> 8951<dd> 8952<p><code>std::unique_ptr<T>(reinterpret_cast<typename 8953std::unique_ptr<T>::element_type*>(p.release()))</code>.</p> 8954</dd> 8955</dl> 8956</div> 8957</li> 8958</ul> 8959</div> 8960</div> 8961</div> 8962<div class="sect2"> 8963<h3 id="pointer_cast_example">Example</h3> 8964<div class="paragraph"> 8965<p>The following example demonstrates how the generic pointer casts help us 8966create pointer independent code.</p> 8967</div> 8968<div class="listingblock"> 8969<div class="content"> 8970<pre class="highlight"><code>#include <boost/pointer_cast.hpp> 8971#include <boost/shared_ptr.hpp> 8972 8973class base { 8974public: 8975 virtual ~base() { } 8976}; 8977 8978class derived : public base { }; 8979 8980template<class Ptr> 8981void check_if_it_is_derived(const Ptr& ptr) 8982{ 8983 assert(boost::dynamic_pointer_cast<derived>(ptr) != 0); 8984} 8985 8986int main() 8987{ 8988 base* ptr = new derived; 8989 boost::shared_ptr<base> sptr(new derived); 8990 8991 check_if_it_is_derived(ptr); 8992 check_if_it_is_derived(sptr); 8993 8994 delete ptr; 8995}</code></pre> 8996</div> 8997</div> 8998</div> 8999</div> 9000</div> 9001<div class="sect1"> 9002<h2 id="pointer_to_other">pointer_to_other</h2> 9003<div class="sectionbody"> 9004<div class="sect2"> 9005<h3 id="pointer_to_other_description">Description</h3> 9006<div class="paragraph"> 9007<p>The <code>pointer_to_other</code> utility provides a way, given a source pointer type, to obtain a pointer of the same type 9008to another pointee type.</p> 9009</div> 9010<div class="paragraph"> 9011<p>There is test/example code in <a href="../../test/pointer_to_other_test.cpp">pointer_to_other_test.cpp</a>.</p> 9012</div> 9013</div> 9014<div class="sect2"> 9015<h3 id="pointer_to_other_rationale">Rationale</h3> 9016<div class="paragraph"> 9017<p>When building pointer independent classes, like memory managers, allocators, or containers, there is often a need to 9018define pointers generically, so that if a template parameter represents a pointer (for example, a raw or smart pointer 9019to an <code>int</code>), we can define another pointer of the same type to another pointee (a raw or smart pointer to a <code>float</code>.)</p> 9020</div> 9021<div class="listingblock"> 9022<div class="content"> 9023<pre class="highlight"><code>template <class IntPtr> class FloatPointerHolder 9024{ 9025 // Let's define a pointer to a float 9026 9027 typedef typename boost::pointer_to_other 9028 <IntPtr, float>::type float_ptr_t; 9029 9030 float_ptr_t float_ptr; 9031};</code></pre> 9032</div> 9033</div> 9034</div> 9035<div class="sect2"> 9036<h3 id="pointer_to_other_synopsis">Synopsis</h3> 9037<div class="paragraph"> 9038<p><code>pointer_to_other</code> is defined in <code><boost/smart_ptr/pointer_to_other.hpp></code>.</p> 9039</div> 9040<div class="listingblock"> 9041<div class="content"> 9042<pre class="highlight"><code>namespace boost { 9043 9044 template<class T, class U> struct pointer_to_other; 9045 9046 template<class T, class U, 9047 template <class> class Sp> 9048 struct pointer_to_other< Sp<T>, U > 9049 { 9050 typedef Sp<U> type; 9051 }; 9052 9053 template<class T, class T2, class U, 9054 template <class, class> class Sp> 9055 struct pointer_to_other< Sp<T, T2>, U > 9056 { 9057 typedef Sp<U, T2> type; 9058 }; 9059 9060 template<class T, class T2, class T3, class U, 9061 template <class, class, class> class Sp> 9062 struct pointer_to_other< Sp<T, T2, T3>, U > 9063 { 9064 typedef Sp<U, T2, T3> type; 9065 }; 9066 9067 template<class T, class U> 9068 struct pointer_to_other< T*, U > 9069 { 9070 typedef U* type; 9071 }; 9072}</code></pre> 9073</div> 9074</div> 9075<div class="paragraph"> 9076<p>If these definitions are not correct for a specific smart pointer, we can define a specialization of <code>pointer_to_other</code>.</p> 9077</div> 9078</div> 9079<div class="sect2"> 9080<h3 id="pointer_to_other_example">Example</h3> 9081<div class="listingblock"> 9082<div class="content"> 9083<pre class="highlight"><code>// Let's define a memory allocator that can 9084// work with raw and smart pointers 9085 9086#include <boost/pointer_to_other.hpp> 9087 9088template <class VoidPtr> 9089class memory_allocator 9090{ 9091 // Predefine a memory_block 9092 9093 struct block; 9094 9095 // Define a pointer to a memory_block from a void pointer 9096 // If VoidPtr is void *, block_ptr_t is block* 9097 // If VoidPtr is smart_ptr<void>, block_ptr_t is smart_ptr<block> 9098 9099 typedef typename boost::pointer_to_other 9100 <VoidPtr, block>::type block_ptr_t; 9101 9102 struct block 9103 { 9104 std::size_t size; 9105 block_ptr_t next_block; 9106 }; 9107 9108 block_ptr_t free_blocks; 9109};</code></pre> 9110</div> 9111</div> 9112<div class="paragraph"> 9113<p>As we can see, using <code>pointer_to_other</code> we can create pointer independent code.</p> 9114</div> 9115</div> 9116</div> 9117</div> 9118<div class="sect1"> 9119<h2 id="atomic_shared_ptr">atomic_shared_ptr</h2> 9120<div class="sectionbody"> 9121<div class="sect2"> 9122<h3 id="atomic_shared_ptr_description">Description</h3> 9123<div class="paragraph"> 9124<p>The class template <code>atomic_shared_ptr<T></code> implements the interface of <code>std::atomic</code> 9125for a contained value of type <code>shared_ptr<T></code>. Concurrent access to <code>atomic_shared_ptr</code> 9126is not a data race.</p> 9127</div> 9128</div> 9129<div class="sect2"> 9130<h3 id="atomic_shared_ptr_synopsis">Synopsis</h3> 9131<div class="paragraph"> 9132<p><code>atomic_shared_ptr</code> is defined in <code><boost/smart_ptr/atomic_shared_ptr.hpp></code>.</p> 9133</div> 9134<div class="listingblock"> 9135<div class="content"> 9136<pre class="highlight"><code>namespace boost { 9137 9138 template<class T> class atomic_shared_ptr { 9139 private: 9140 9141 shared_ptr<T> p_; // exposition only 9142 9143 atomic_shared_ptr(const atomic_shared_ptr&) = delete; 9144 atomic_shared_ptr& operator=(const atomic_shared_ptr&) = delete; 9145 9146 public: 9147 9148 constexpr atomic_shared_ptr() noexcept; 9149 atomic_shared_ptr( shared_ptr<T> p ) noexcept; 9150 9151 atomic_shared_ptr& operator=( shared_ptr<T> r ) noexcept; 9152 9153 bool is_lock_free() const noexcept; 9154 9155 shared_ptr<T> load( int = 0 ) const noexcept; 9156 operator shared_ptr<T>() const noexcept; 9157 9158 void store( shared_ptr<T> r, int = 0 ) noexcept; 9159 9160 shared_ptr<T> exchange( shared_ptr<T> r, int = 0 ) noexcept; 9161 9162 bool compare_exchange_weak( shared_ptr<T>& v, const shared_ptr<T>& w, int, int ) noexcept; 9163 bool compare_exchange_weak( shared_ptr<T>& v, const shared_ptr<T>& w, int = 0 ) noexcept; 9164 bool compare_exchange_strong( shared_ptr<T>& v, const shared_ptr<T>& w, int, int ) noexcept; 9165 bool compare_exchange_strong( shared_ptr<T>& v, const shared_ptr<T>& w, int = 0 ) noexcept; 9166 9167 bool compare_exchange_weak( shared_ptr<T>& v, shared_ptr<T>&& w, int, int ) noexcept; 9168 bool compare_exchange_weak( shared_ptr<T>& v, shared_ptr<T>&& w, int = 0 ) noexcept; 9169 bool compare_exchange_strong( shared_ptr<T>& v, shared_ptr<T>&& w, int, int ) noexcept; 9170 bool compare_exchange_strong( shared_ptr<T>& v, shared_ptr<T>&& w, int = 0 ) noexcept; 9171 }; 9172}</code></pre> 9173</div> 9174</div> 9175</div> 9176<div class="sect2"> 9177<h3 id="atomic_shared_ptr_members">Members</h3> 9178<div class="listingblock"> 9179<div class="content"> 9180<pre class="highlight"><code>constexpr atomic_shared_ptr() noexcept;</code></pre> 9181</div> 9182</div> 9183<div class="ulist none"> 9184<ul class="none"> 9185<li> 9186<p></p> 9187<div class="dlist"> 9188<dl> 9189<dt class="hdlist1">Effects</dt> 9190<dd> 9191<p>Default-initializes <code>p_</code>.</p> 9192</dd> 9193</dl> 9194</div> 9195</li> 9196</ul> 9197</div> 9198<div class="listingblock"> 9199<div class="content"> 9200<pre class="highlight"><code>atomic_shared_ptr( shared_ptr<T> p ) noexcept;</code></pre> 9201</div> 9202</div> 9203<div class="ulist none"> 9204<ul class="none"> 9205<li> 9206<p></p> 9207<div class="dlist"> 9208<dl> 9209<dt class="hdlist1">Effects</dt> 9210<dd> 9211<p>Initializes <code>p_</code> to <code>p</code>.</p> 9212</dd> 9213</dl> 9214</div> 9215</li> 9216</ul> 9217</div> 9218<div class="listingblock"> 9219<div class="content"> 9220<pre class="highlight"><code>atomic_shared_ptr& operator=( shared_ptr<T> r ) noexcept;</code></pre> 9221</div> 9222</div> 9223<div class="ulist none"> 9224<ul class="none"> 9225<li> 9226<p></p> 9227<div class="dlist"> 9228<dl> 9229<dt class="hdlist1">Effects</dt> 9230<dd> 9231<p><code>p_.swap(r)</code>.</p> 9232</dd> 9233<dt class="hdlist1">Returns</dt> 9234<dd> 9235<p><code>*this</code>.</p> 9236</dd> 9237</dl> 9238</div> 9239</li> 9240</ul> 9241</div> 9242<div class="listingblock"> 9243<div class="content"> 9244<pre class="highlight"><code>bool is_lock_free() const noexcept;</code></pre> 9245</div> 9246</div> 9247<div class="ulist none"> 9248<ul class="none"> 9249<li> 9250<p></p> 9251<div class="dlist"> 9252<dl> 9253<dt class="hdlist1">Returns</dt> 9254<dd> 9255<p><code>false</code>.</p> 9256</dd> 9257</dl> 9258</div> 9259</li> 9260</ul> 9261</div> 9262<div class="admonitionblock note"> 9263<table> 9264<tr> 9265<td class="icon"> 9266<div class="title">Note</div> 9267</td> 9268<td class="content"> 9269This implementation is not lock-free. 9270</td> 9271</tr> 9272</table> 9273</div> 9274<div class="listingblock"> 9275<div class="content"> 9276<pre class="highlight"><code>shared_ptr<T> load( int = 0 ) const noexcept;</code></pre> 9277</div> 9278</div> 9279<div class="listingblock"> 9280<div class="content"> 9281<pre class="highlight"><code>operator shared_ptr<T>() const noexcept;</code></pre> 9282</div> 9283</div> 9284<div class="ulist none"> 9285<ul class="none"> 9286<li> 9287<p></p> 9288<div class="dlist"> 9289<dl> 9290<dt class="hdlist1">Returns</dt> 9291<dd> 9292<p><code>p_</code>.</p> 9293</dd> 9294</dl> 9295</div> 9296</li> 9297</ul> 9298</div> 9299<div class="admonitionblock note"> 9300<table> 9301<tr> 9302<td class="icon"> 9303<div class="title">Note</div> 9304</td> 9305<td class="content"> 9306The <code>int</code> argument is intended to be of type <code>memory_order</code>, but is ignored. 9307 This implementation is lock-based and therefore always sequentially consistent. 9308</td> 9309</tr> 9310</table> 9311</div> 9312<div class="listingblock"> 9313<div class="content"> 9314<pre class="highlight"><code>void store( shared_ptr<T> r, int = 0 ) noexcept;</code></pre> 9315</div> 9316</div> 9317<div class="ulist none"> 9318<ul class="none"> 9319<li> 9320<p></p> 9321<div class="dlist"> 9322<dl> 9323<dt class="hdlist1">Effects</dt> 9324<dd> 9325<p><code>p_.swap(r)</code>.</p> 9326</dd> 9327</dl> 9328</div> 9329</li> 9330</ul> 9331</div> 9332<div class="listingblock"> 9333<div class="content"> 9334<pre class="highlight"><code>shared_ptr<T> exchange( shared_ptr<T> r, int = 0 ) noexcept;</code></pre> 9335</div> 9336</div> 9337<div class="ulist none"> 9338<ul class="none"> 9339<li> 9340<p></p> 9341<div class="dlist"> 9342<dl> 9343<dt class="hdlist1">Effects</dt> 9344<dd> 9345<p><code>p_.swap(r)</code>.</p> 9346</dd> 9347<dt class="hdlist1">Returns</dt> 9348<dd> 9349<p>The old value of <code>p_</code>.</p> 9350</dd> 9351</dl> 9352</div> 9353</li> 9354</ul> 9355</div> 9356<div class="listingblock"> 9357<div class="content"> 9358<pre class="highlight"><code>bool compare_exchange_weak( shared_ptr<T>& v, const shared_ptr<T>& w, int, int ) noexcept;</code></pre> 9359</div> 9360</div> 9361<div class="listingblock"> 9362<div class="content"> 9363<pre class="highlight"><code>bool compare_exchange_weak( shared_ptr<T>& v, const shared_ptr<T>& w, int = 0 ) noexcept;</code></pre> 9364</div> 9365</div> 9366<div class="listingblock"> 9367<div class="content"> 9368<pre class="highlight"><code>bool compare_exchange_strong( shared_ptr<T>& v, const shared_ptr<T>& w, int, int ) noexcept;</code></pre> 9369</div> 9370</div> 9371<div class="listingblock"> 9372<div class="content"> 9373<pre class="highlight"><code>bool compare_exchange_strong( shared_ptr<T>& v, const shared_ptr<T>& w, int = 0 ) noexcept;</code></pre> 9374</div> 9375</div> 9376<div class="ulist none"> 9377<ul class="none"> 9378<li> 9379<p></p> 9380<div class="dlist"> 9381<dl> 9382<dt class="hdlist1">Effects</dt> 9383<dd> 9384<p>If <code>p_</code> is equivalent to <code>v</code>, assigns <code>w</code> to <code>p_</code>, otherwise assigns <code>p_</code> to <code>v</code>.</p> 9385</dd> 9386<dt class="hdlist1">Returns</dt> 9387<dd> 9388<p><code>true</code> if <code>p_</code> was equivalent to <code>v</code>, <code>false</code> otherwise.</p> 9389</dd> 9390<dt class="hdlist1">Remarks</dt> 9391<dd> 9392<p>Two <code>shared_ptr</code> instances are equivalent if they store the same pointer value and <em>share ownership</em>.</p> 9393</dd> 9394</dl> 9395</div> 9396</li> 9397</ul> 9398</div> 9399<div class="listingblock"> 9400<div class="content"> 9401<pre class="highlight"><code>bool compare_exchange_weak( shared_ptr<T>& v, shared_ptr<T>&& w, int, int ) noexcept;</code></pre> 9402</div> 9403</div> 9404<div class="listingblock"> 9405<div class="content"> 9406<pre class="highlight"><code>bool compare_exchange_weak( shared_ptr<T>& v, shared_ptr<T>&& w, int = 0 ) noexcept;</code></pre> 9407</div> 9408</div> 9409<div class="listingblock"> 9410<div class="content"> 9411<pre class="highlight"><code>bool compare_exchange_strong( shared_ptr<T>& v, shared_ptr<T>&& w, int, int ) noexcept;</code></pre> 9412</div> 9413</div> 9414<div class="listingblock"> 9415<div class="content"> 9416<pre class="highlight"><code>bool compare_exchange_strong( shared_ptr<T>& v, shared_ptr<T>&& w, int = 0 ) noexcept;</code></pre> 9417</div> 9418</div> 9419<div class="ulist none"> 9420<ul class="none"> 9421<li> 9422<p></p> 9423<div class="dlist"> 9424<dl> 9425<dt class="hdlist1">Effects</dt> 9426<dd> 9427<p>If <code>p_</code> is equivalent to <code>v</code>, assigns <code>std::move(w)</code> to <code>p_</code>, otherwise assigns <code>p_</code> to <code>v</code>.</p> 9428</dd> 9429<dt class="hdlist1">Returns</dt> 9430<dd> 9431<p><code>true</code> if <code>p_</code> was equivalent to <code>v</code>, <code>false</code> otherwise.</p> 9432</dd> 9433<dt class="hdlist1">Remarks</dt> 9434<dd> 9435<p>The old value of <code>w</code> is not preserved in either case.</p> 9436</dd> 9437</dl> 9438</div> 9439</li> 9440</ul> 9441</div> 9442</div> 9443</div> 9444</div> 9445<div class="sect1"> 9446<h2 id="owner_less">owner_less</h2> 9447<div class="sectionbody"> 9448<div class="sect2"> 9449<h3 id="owner_less_description">Description</h3> 9450<div class="paragraph"> 9451<p><code>owner_less<T></code> is a helper function object that compares two smart 9452pointer objects using <code>owner_before</code>. It is only provided for compatibility 9453with C++11 and corresponds to the standard component of the same name.</p> 9454</div> 9455<div class="paragraph"> 9456<p>When using Boost smart pointers, the use of <code>owner_less</code> is unnecessary, as 9457the supplied <code>operator<</code> overloads (and, correspondingly, <code>std::less</code>) return 9458the same result.</p> 9459</div> 9460</div> 9461<div class="sect2"> 9462<h3 id="owner_less_synopsis">Synopsis</h3> 9463<div class="paragraph"> 9464<p><code>owner_less</code> is defined in <code><boost/smart_ptr/owner_less.hpp></code>.</p> 9465</div> 9466<div class="listingblock"> 9467<div class="content"> 9468<pre class="highlight"><code>namespace boost { 9469 9470 template<class T = void> struct owner_less 9471 { 9472 typedef bool result_type; 9473 typedef T first_argument_type; 9474 typedef T second_argument_type; 9475 9476 template<class U, class V> bool operator()( U const & u, V const & v ) const noexcept; 9477 }; 9478}</code></pre> 9479</div> 9480</div> 9481</div> 9482<div class="sect2"> 9483<h3 id="owner_less_members">Members</h3> 9484<div class="listingblock"> 9485<div class="content"> 9486<pre class="highlight"><code>template<class U, class V> bool operator()( U const & u, V const & v ) const noexcept;</code></pre> 9487</div> 9488</div> 9489<div class="ulist none"> 9490<ul class="none"> 9491<li> 9492<p></p> 9493<div class="dlist"> 9494<dl> 9495<dt class="hdlist1">Returns</dt> 9496<dd> 9497<p><code>u.owner_before( v )</code>.</p> 9498</dd> 9499</dl> 9500</div> 9501</li> 9502</ul> 9503</div> 9504</div> 9505</div> 9506</div> 9507<div class="sect1"> 9508<h2 id="owner_equal_to">owner_equal_to</h2> 9509<div class="sectionbody"> 9510<div class="sect2"> 9511<h3 id="owner_equal_to_description">Description</h3> 9512<div class="paragraph"> 9513<p><code>owner_equal_to<T></code> is a helper function object that compares two smart 9514pointer objects using <code>owner_equals</code>.</p> 9515</div> 9516</div> 9517<div class="sect2"> 9518<h3 id="owner_equal_to_synopsis">Synopsis</h3> 9519<div class="paragraph"> 9520<p><code>owner_equal_to</code> is defined in <code><boost/smart_ptr/owner_equal_to.hpp></code>.</p> 9521</div> 9522<div class="listingblock"> 9523<div class="content"> 9524<pre class="highlight"><code>namespace boost { 9525 9526 template<class T = void> struct owner_equal_to 9527 { 9528 typedef bool result_type; 9529 typedef T first_argument_type; 9530 typedef T second_argument_type; 9531 9532 template<class U, class V> bool operator()( U const & u, V const & v ) const noexcept; 9533 }; 9534}</code></pre> 9535</div> 9536</div> 9537</div> 9538<div class="sect2"> 9539<h3 id="owner_equal_to_members">Members</h3> 9540<div class="listingblock"> 9541<div class="content"> 9542<pre class="highlight"><code>template<class U, class V> bool operator()( U const & u, V const & v ) const noexcept;</code></pre> 9543</div> 9544</div> 9545<div class="ulist none"> 9546<ul class="none"> 9547<li> 9548<p></p> 9549<div class="dlist"> 9550<dl> 9551<dt class="hdlist1">Returns</dt> 9552<dd> 9553<p><code>u.owner_equals( v )</code>.</p> 9554</dd> 9555</dl> 9556</div> 9557</li> 9558</ul> 9559</div> 9560</div> 9561</div> 9562</div> 9563<div class="sect1"> 9564<h2 id="owner_hash">owner_hash</h2> 9565<div class="sectionbody"> 9566<div class="sect2"> 9567<h3 id="owner_hash_to_description">Description</h3> 9568<div class="paragraph"> 9569<p><code>owner_hash<T></code> is a helper function object that takes a smart pointer <code>p</code> 9570and returns <code>p.owner_hash_value()</code>. It’s useful for creating unordered 9571containers of <code>shared_ptr</code> that use ownership-based equality, instead of 9572the default pointer value equality. (It can be used with <code>weak_ptr</code> too, 9573but there’s no need, because <code>boost::hash</code> and <code>std::hash</code> for <code>weak_ptr</code> 9574already use ownership-based equality.)</p> 9575</div> 9576</div> 9577<div class="sect2"> 9578<h3 id="owner_hash_to_example">Example</h3> 9579<div class="listingblock"> 9580<div class="content"> 9581<pre class="highlight"><code>std::unordered_set< boost::shared_ptr<void>, 9582 boost::owner_hash< boost::shared_ptr<void> >, 9583 boost::owner_equal_to< boost::shared_ptr<void> > > set;</code></pre> 9584</div> 9585</div> 9586</div> 9587<div class="sect2"> 9588<h3 id="owner_hash_to_synopsis">Synopsis</h3> 9589<div class="paragraph"> 9590<p><code>owner_hash</code> is defined in <code><boost/smart_ptr/owner_hash.hpp></code>.</p> 9591</div> 9592<div class="listingblock"> 9593<div class="content"> 9594<pre class="highlight"><code>namespace boost { 9595 9596 template<class T> struct owner_hash 9597 { 9598 typedef std::size_t result_type; 9599 typedef T argument_type; 9600 9601 std::size_t operator()( T const & p ) const noexcept; 9602 }; 9603}</code></pre> 9604</div> 9605</div> 9606</div> 9607<div class="sect2"> 9608<h3 id="owner_hash_to_members">Members</h3> 9609<div class="listingblock"> 9610<div class="content"> 9611<pre class="highlight"><code>std::size_t operator()( T const & p ) const noexcept;</code></pre> 9612</div> 9613</div> 9614<div class="ulist none"> 9615<ul class="none"> 9616<li> 9617<p></p> 9618<div class="dlist"> 9619<dl> 9620<dt class="hdlist1">Returns</dt> 9621<dd> 9622<p><code>p.owner_hash_value()</code>.</p> 9623</dd> 9624</dl> 9625</div> 9626</li> 9627</ul> 9628</div> 9629</div> 9630</div> 9631</div> 9632<div class="sect1"> 9633<h2 id="techniques">Appendix A: Smart Pointer Programming Techniques</h2> 9634<div class="sectionbody"> 9635<div class="sect2"> 9636<h3 id="techniques_incomplete">Using incomplete classes for implementation hiding</h3> 9637<div class="paragraph"> 9638<p>A proven technique (that works in C, too) for separating interface from implementation is to use a pointer to an incomplete class as an opaque handle:</p> 9639</div> 9640<div class="listingblock"> 9641<div class="content"> 9642<pre class="highlight"><code>class FILE; 9643 9644FILE * fopen(char const * name, char const * mode); 9645void fread(FILE * f, void * data, size_t size); 9646void fclose(FILE * f);</code></pre> 9647</div> 9648</div> 9649<div class="paragraph"> 9650<p>It is possible to express the above interface using <code>shared_ptr</code>, eliminating the need to manually call <code>fclose</code>:</p> 9651</div> 9652<div class="listingblock"> 9653<div class="content"> 9654<pre class="highlight"><code>class FILE; 9655 9656shared_ptr<FILE> fopen(char const * name, char const * mode); 9657void fread(shared_ptr<FILE> f, void * data, size_t size);</code></pre> 9658</div> 9659</div> 9660<div class="paragraph"> 9661<p>This technique relies on <code>shared_ptr</code>’s ability to execute a custom deleter, eliminating the explicit call to <code>fclose</code>, and on the fact that <code>shared_ptr<X></code> can be copied and destroyed when <code>X</code> is incomplete.</p> 9662</div> 9663</div> 9664<div class="sect2"> 9665<h3 id="techniques_the_pimpl_idiom">The "Pimpl" idiom</h3> 9666<div class="paragraph"> 9667<p>A C++ specific variation of the incomplete class pattern is the "Pimpl" idiom. The incomplete class is not exposed to the user; it is hidden behind a forwarding facade. <code>shared_ptr</code> can be used to implement a "Pimpl":</p> 9668</div> 9669<div class="listingblock"> 9670<div class="content"> 9671<pre class="highlight"><code>// file.hpp: 9672 9673class file 9674{ 9675private: 9676 9677 class impl; 9678 shared_ptr<impl> pimpl_; 9679 9680public: 9681 9682 file(char const * name, char const * mode); 9683 9684 // compiler generated members are fine and useful 9685 9686 void read(void * data, size_t size); 9687}; 9688 9689// file.cpp: 9690 9691#include "file.hpp" 9692 9693class file::impl 9694{ 9695private: 9696 9697 impl(impl const &); 9698 impl & operator=(impl const &); 9699 9700 // private data 9701 9702public: 9703 9704 impl(char const * name, char const * mode) { ... } 9705 ~impl() { ... } 9706 void read(void * data, size_t size) { ... } 9707}; 9708 9709file::file(char const * name, char const * mode): pimpl_(new impl(name, mode)) 9710{ 9711} 9712 9713void file::read(void * data, size_t size) 9714{ 9715 pimpl_->read(data, size); 9716}</code></pre> 9717</div> 9718</div> 9719<div class="paragraph"> 9720<p>The key thing to note here is that the compiler-generated copy constructor, assignment operator, and destructor all have a sensible meaning. As a result, <code>file</code> is <code>CopyConstructible</code> and <code>Assignable</code>, allowing its use in standard containers.</p> 9721</div> 9722</div> 9723<div class="sect2"> 9724<h3 id="techniques_using_abstract_classes_for_implementation_hiding">Using abstract classes for implementation hiding</h3> 9725<div class="paragraph"> 9726<p>Another widely used C++ idiom for separating inteface and implementation is to use abstract base classes and factory functions. 9727The abstract classes are sometimes called "interfaces" and the pattern is known as "interface-based programming". Again, 9728<code>shared_ptr</code> can be used as the return type of the factory functions:</p> 9729</div> 9730<div class="listingblock"> 9731<div class="content"> 9732<pre class="highlight"><code>// X.hpp: 9733 9734class X 9735{ 9736public: 9737 9738 virtual void f() = 0; 9739 virtual void g() = 0; 9740 9741protected: 9742 9743 ~X() {} 9744}; 9745 9746shared_ptr<X> createX(); 9747 9748// X.cpp: 9749 9750class X_impl: public X 9751{ 9752private: 9753 9754 X_impl(X_impl const &); 9755 X_impl & operator=(X_impl const &); 9756 9757public: 9758 9759 virtual void f() 9760 { 9761 // ... 9762 } 9763 9764 virtual void g() 9765 { 9766 // ... 9767 } 9768}; 9769 9770shared_ptr<X> createX() 9771{ 9772 shared_ptr<X> px(new X_impl); 9773 return px; 9774}</code></pre> 9775</div> 9776</div> 9777<div class="paragraph"> 9778<p>A key property of <code>shared_ptr</code> is that the allocation, construction, deallocation, and destruction details are captured at the point of construction, inside the factory function.</p> 9779</div> 9780<div class="paragraph"> 9781<p>Note the protected and nonvirtual destructor in the example above. The client code cannot, and does not need to, delete a pointer to <code>X</code>; the <code>shared_ptr<X></code> instance returned from <code>createX</code> will correctly call <code>~X_impl</code>.</p> 9782</div> 9783</div> 9784<div class="sect2"> 9785<h3 id="techniques_preventing_delete_px_get">Preventing <code>delete px.get()</code></h3> 9786<div class="paragraph"> 9787<p>It is often desirable to prevent client code from deleting a pointer that is being managed by <code>shared_ptr</code>. The previous technique showed one possible approach, using a protected destructor. Another alternative is to use a private deleter:</p> 9788</div> 9789<div class="listingblock"> 9790<div class="content"> 9791<pre class="highlight"><code>class X 9792{ 9793private: 9794 9795 ~X(); 9796 9797 class deleter; 9798 friend class deleter; 9799 9800 class deleter 9801 { 9802 public: 9803 9804 void operator()(X * p) { delete p; } 9805 }; 9806 9807public: 9808 9809 static shared_ptr<X> create() 9810 { 9811 shared_ptr<X> px(new X, X::deleter()); 9812 return px; 9813 } 9814};</code></pre> 9815</div> 9816</div> 9817</div> 9818<div class="sect2"> 9819<h3 id="techniques_encapsulating_allocation_details_wrapping_factory_functions">Encapsulating allocation details, wrapping factory functions</h3> 9820<div class="paragraph"> 9821<p><code>shared_ptr</code> can be used in creating C++ wrappers over existing C style library interfaces that return raw pointers from their factory functions 9822to encapsulate allocation details. As an example, consider this interface, where <code>CreateX</code> might allocate <code>X</code> from its own private heap, <code>~X</code> may 9823be inaccessible, or <code>X</code> may be incomplete:</p> 9824</div> 9825<div class="literalblock"> 9826<div class="content"> 9827<pre>X * CreateX(); 9828void DestroyX(X *);</pre> 9829</div> 9830</div> 9831<div class="paragraph"> 9832<p>The only way to reliably destroy a pointer returned by <code>CreateX</code> is to call <code>DestroyX</code>.</p> 9833</div> 9834<div class="paragraph"> 9835<p>Here is how a <code>shared_ptr</code>-based wrapper may look like:</p> 9836</div> 9837<div class="literalblock"> 9838<div class="content"> 9839<pre>shared_ptr<X> createX() 9840{ 9841 shared_ptr<X> px(CreateX(), DestroyX); 9842 return px; 9843}</pre> 9844</div> 9845</div> 9846<div class="paragraph"> 9847<p>Client code that calls <code>createX</code> still does not need to know how the object has been allocated, but now the destruction is automatic.</p> 9848</div> 9849</div> 9850<div class="sect2"> 9851<h3 id="techniques_static">Using a shared_ptr to hold a pointer to a statically allocated object</h3> 9852<div class="paragraph"> 9853<p>Sometimes it is desirable to create a <code>shared_ptr</code> to an already existing object, so that the <code>shared_ptr</code> does not attempt to destroy the 9854object when there are no more references left. As an example, the factory function:</p> 9855</div> 9856<div class="literalblock"> 9857<div class="content"> 9858<pre>shared_ptr<X> createX();</pre> 9859</div> 9860</div> 9861<div class="paragraph"> 9862<p>in certain situations may need to return a pointer to a statically allocated <code>X</code> instance.</p> 9863</div> 9864<div class="paragraph"> 9865<p>The solution is to use a custom deleter that does nothing:</p> 9866</div> 9867<div class="listingblock"> 9868<div class="content"> 9869<pre class="highlight"><code>struct null_deleter 9870{ 9871 void operator()(void const *) const 9872 { 9873 } 9874}; 9875 9876static X x; 9877 9878shared_ptr<X> createX() 9879{ 9880 shared_ptr<X> px(&x, null_deleter()); 9881 return px; 9882}</code></pre> 9883</div> 9884</div> 9885<div class="paragraph"> 9886<p>The same technique works for any object known to outlive the pointer.</p> 9887</div> 9888</div> 9889<div class="sect2"> 9890<h3 id="techniques_using_a_shared_ptr_to_hold_a_pointer_to_a_com_object">Using a shared_ptr to hold a pointer to a COM Object</h3> 9891<div class="paragraph"> 9892<p>Background: COM objects have an embedded reference count and two member functions that manipulate it. <code>AddRef()</code> increments the count. 9893<code>Release()</code> decrements the count and destroys itself when the count drops to zero.</p> 9894</div> 9895<div class="paragraph"> 9896<p>It is possible to hold a pointer to a COM object in a <code>shared_ptr</code>:</p> 9897</div> 9898<div class="literalblock"> 9899<div class="content"> 9900<pre>shared_ptr<IWhatever> make_shared_from_COM(IWhatever * p) 9901{ 9902 p->AddRef(); 9903 shared_ptr<IWhatever> pw(p, mem_fn(&IWhatever::Release)); 9904 return pw; 9905}</pre> 9906</div> 9907</div> 9908<div class="paragraph"> 9909<p>Note, however, that <code>shared_ptr</code> copies created from <code>pw</code> will not "register" in the embedded count of the COM object; 9910they will share the single reference created in <code>make_shared_from_COM</code>. Weak pointers created from <code>pw</code> will be invalidated when the last 9911<code>shared_ptr</code> is destroyed, regardless of whether the COM object itself is still alive.</p> 9912</div> 9913<div class="paragraph"> 9914<p>As <a href="../../../../libs/bind/mem_fn.html#Q3">explained</a> in the <code>mem_fn</code> documentation, you need to <code>#define BOOST_MEM_FN_ENABLE_STDCALL</code> first.</p> 9915</div> 9916</div> 9917<div class="sect2"> 9918<h3 id="techniques_intrusive">Using a shared_ptr to hold a pointer to an object with an embedded reference count</h3> 9919<div class="paragraph"> 9920<p>This is a generalization of the above technique. The example assumes that the object implements the two functions required by <code><a href="#intrusive_ptr">intrusive_ptr</a></code>, 9921<code>intrusive_ptr_add_ref</code> and <code>intrusive_ptr_release</code>:</p> 9922</div> 9923<div class="listingblock"> 9924<div class="content"> 9925<pre class="highlight"><code>template<class T> struct intrusive_deleter 9926{ 9927 void operator()(T * p) 9928 { 9929 if(p) intrusive_ptr_release(p); 9930 } 9931}; 9932 9933shared_ptr<X> make_shared_from_intrusive(X * p) 9934{ 9935 if(p) intrusive_ptr_add_ref(p); 9936 shared_ptr<X> px(p, intrusive_deleter<X>()); 9937 return px; 9938}</code></pre> 9939</div> 9940</div> 9941</div> 9942<div class="sect2"> 9943<h3 id="techniques_using_a_shared_ptr_to_hold_another_shared_ownership_smart_pointer">Using a shared_ptr to hold another shared ownership smart pointer</h3> 9944<div class="paragraph"> 9945<p>One of the design goals of <code>shared_ptr</code> is to be used in library interfaces. It is possible to encounter a situation where a library takes a 9946<code>shared_ptr</code> argument, but the object at hand is being managed by a different reference counted or linked smart pointer.</p> 9947</div> 9948<div class="paragraph"> 9949<p>It is possible to exploit <code>shared_ptr</code>’s custom deleter feature to wrap this existing smart pointer behind a <code>shared_ptr</code> facade:</p> 9950</div> 9951<div class="listingblock"> 9952<div class="content"> 9953<pre class="highlight"><code>template<class P> struct smart_pointer_deleter 9954{ 9955private: 9956 9957 P p_; 9958 9959public: 9960 9961 smart_pointer_deleter(P const & p): p_(p) 9962 { 9963 } 9964 9965 void operator()(void const *) 9966 { 9967 p_.reset(); 9968 } 9969 9970 P const & get() const 9971 { 9972 return p_; 9973 } 9974}; 9975 9976shared_ptr<X> make_shared_from_another(another_ptr<X> qx) 9977{ 9978 shared_ptr<X> px(qx.get(), smart_pointer_deleter< another_ptr<X> >(qx)); 9979 return px; 9980}</code></pre> 9981</div> 9982</div> 9983<div class="paragraph"> 9984<p>One subtle point is that deleters are not allowed to throw exceptions, and the above example as written assumes that <code>p_.reset()</code> doesn’t throw. 9985If this is not the case, <code>p_.reset();</code> should be wrapped in a <code>try {} catch(…​) {}</code> block that ignores exceptions. In the (usually unlikely) event 9986when an exception is thrown and ignored, <code>p_</code> will be released when the lifetime of the deleter ends. This happens when all references, including 9987weak pointers, are destroyed or reset.</p> 9988</div> 9989<div class="paragraph"> 9990<p>Another twist is that it is possible, given the above <code>shared_ptr</code> instance, to recover the original smart pointer, using <code><a href="#shared_ptr_get_deleter">get_deleter</a></code>:</p> 9991</div> 9992<div class="listingblock"> 9993<div class="content"> 9994<pre class="highlight"><code>void extract_another_from_shared(shared_ptr<X> px) 9995{ 9996 typedef smart_pointer_deleter< another_ptr<X> > deleter; 9997 9998 if(deleter const * pd = get_deleter<deleter>(px)) 9999 { 10000 another_ptr<X> qx = pd->get(); 10001 } 10002 else 10003 { 10004 // not one of ours 10005 } 10006}</code></pre> 10007</div> 10008</div> 10009</div> 10010<div class="sect2"> 10011<h3 id="techniques_from_raw">Obtaining a shared_ptr from a raw pointer</h3> 10012<div class="paragraph"> 10013<p>Sometimes it is necessary to obtain a <code>shared_ptr</code> given a raw pointer to an object that is already managed by another <code>shared_ptr</code> instance. Example:</p> 10014</div> 10015<div class="literalblock"> 10016<div class="content"> 10017<pre>void f(X * p) 10018{ 10019 shared_ptr<X> px(???); 10020}</pre> 10021</div> 10022</div> 10023<div class="paragraph"> 10024<p>Inside <code>f</code>, we’d like to create a <code>shared_ptr</code> to <code>*p</code>.</p> 10025</div> 10026<div class="paragraph"> 10027<p>In the general case, this problem has no solution. One approach is to modify <code>f</code> to take a <code>shared_ptr</code>, if possible:</p> 10028</div> 10029<div class="literalblock"> 10030<div class="content"> 10031<pre>void f(shared_ptr<X> px);</pre> 10032</div> 10033</div> 10034<div class="paragraph"> 10035<p>The same transformation can be used for nonvirtual member functions, to convert the implicit <code>this</code>:</p> 10036</div> 10037<div class="literalblock"> 10038<div class="content"> 10039<pre>void X::f(int m);</pre> 10040</div> 10041</div> 10042<div class="paragraph"> 10043<p>would become a free function with a <code>shared_ptr</code> first argument:</p> 10044</div> 10045<div class="literalblock"> 10046<div class="content"> 10047<pre>void f(shared_ptr<X> this_, int m);</pre> 10048</div> 10049</div> 10050<div class="paragraph"> 10051<p>If <code>f</code> cannot be changed, but <code>X</code> uses intrusive counting, use <code><a href="#techniques_intrusive">make_shared_from_intrusive</a></code> described above. Or, if it’s known that the <code>shared_ptr</code> created in <code>f</code> will never outlive the object, use <a href="#techniques_static">a null deleter</a>.</p> 10052</div> 10053</div> 10054<div class="sect2"> 10055<h3 id="techniques_obtaining_a_shared_ptr_weak_ptr_to_this_in_a_constructor">Obtaining a shared_ptr (weak_ptr) to this in a constructor</h3> 10056<div class="paragraph"> 10057<p>Some designs require objects to register themselves on construction with a central authority. When the registration routines take a <code>shared_ptr</code>, this leads to the question how could a constructor obtain a <code>shared_ptr</code> to <code>this</code>:</p> 10058</div> 10059<div class="listingblock"> 10060<div class="content"> 10061<pre class="highlight"><code>class X 10062{ 10063public: 10064 10065 X() 10066 { 10067 shared_ptr<X> this_(???); 10068 } 10069};</code></pre> 10070</div> 10071</div> 10072<div class="paragraph"> 10073<p>In the general case, the problem cannot be solved. The <code>X</code> instance being constructed can be an automatic variable or a static variable; it can be created on the heap:</p> 10074</div> 10075<div class="literalblock"> 10076<div class="content"> 10077<pre>shared_ptr<X> px(new X);</pre> 10078</div> 10079</div> 10080<div class="paragraph"> 10081<p>but at construction time, <code>px</code> does not exist yet, and it is impossible to create another <code>shared_ptr</code> instance that shares ownership with it.</p> 10082</div> 10083<div class="paragraph"> 10084<p>Depending on context, if the inner <code>shared_ptr this_</code> doesn’t need to keep the object alive, use a <code>null_deleter</code> as explained <a href="#techniques_static">here</a> and <a href="#techniques_weak_without_shared">here</a>. 10085If <code>X</code> is supposed to always live on the heap, and be managed by a <code>shared_ptr</code>, use a static factory function:</p> 10086</div> 10087<div class="listingblock"> 10088<div class="content"> 10089<pre class="highlight"><code>class X 10090{ 10091private: 10092 10093 X() { ... } 10094 10095public: 10096 10097 static shared_ptr<X> create() 10098 { 10099 shared_ptr<X> px(new X); 10100 // use px as 'this_' 10101 return px; 10102 } 10103};</code></pre> 10104</div> 10105</div> 10106</div> 10107<div class="sect2"> 10108<h3 id="techniques_obtaining_a_shared_ptr_to_this">Obtaining a shared_ptr to this</h3> 10109<div class="paragraph"> 10110<p>Sometimes it is needed to obtain a <code>shared_ptr</code> from <code>this</code> in a virtual member function under the assumption that <code>this</code> is already managed by a <code>shared_ptr</code>. 10111The transformations <a href="#techniques_from_raw">described in the previous technique</a> cannot be applied.</p> 10112</div> 10113<div class="paragraph"> 10114<p>A typical example:</p> 10115</div> 10116<div class="listingblock"> 10117<div class="content"> 10118<pre class="highlight"><code>class X 10119{ 10120public: 10121 10122 virtual void f() = 0; 10123 10124protected: 10125 10126 ~X() {} 10127}; 10128 10129class Y 10130{ 10131public: 10132 10133 virtual shared_ptr<X> getX() = 0; 10134 10135protected: 10136 10137 ~Y() {} 10138}; 10139 10140// -- 10141 10142class impl: public X, public Y 10143{ 10144public: 10145 10146 impl() { ... } 10147 10148 virtual void f() { ... } 10149 10150 virtual shared_ptr<X> getX() 10151 { 10152 shared_ptr<X> px(???); 10153 return px; 10154 } 10155};</code></pre> 10156</div> 10157</div> 10158<div class="paragraph"> 10159<p>The solution is to keep a weak pointer to <code>this</code> as a member in <code>impl</code>:</p> 10160</div> 10161<div class="listingblock"> 10162<div class="content"> 10163<pre class="highlight"><code>class impl: public X, public Y 10164{ 10165private: 10166 10167 weak_ptr<impl> weak_this; 10168 10169 impl(impl const &); 10170 impl & operator=(impl const &); 10171 10172 impl() { ... } 10173 10174public: 10175 10176 static shared_ptr<impl> create() 10177 { 10178 shared_ptr<impl> pi(new impl); 10179 pi->weak_this = pi; 10180 return pi; 10181 } 10182 10183 virtual void f() { ... } 10184 10185 virtual shared_ptr<X> getX() 10186 { 10187 shared_ptr<X> px(weak_this); 10188 return px; 10189 } 10190};</code></pre> 10191</div> 10192</div> 10193<div class="paragraph"> 10194<p>The library now includes a helper class template <code><a href="#enable_shared_from_this">enable_shared_from_this</a></code> that can be used to encapsulate the solution:</p> 10195</div> 10196<div class="listingblock"> 10197<div class="content"> 10198<pre class="highlight"><code>class impl: public X, public Y, public enable_shared_from_this<impl> 10199{ 10200public: 10201 10202 impl(impl const &); 10203 impl & operator=(impl const &); 10204 10205public: 10206 10207 virtual void f() { ... } 10208 10209 virtual shared_ptr<X> getX() 10210 { 10211 return shared_from_this(); 10212 } 10213}</code></pre> 10214</div> 10215</div> 10216<div class="paragraph"> 10217<p>Note that you no longer need to manually initialize the <code>weak_ptr</code> member in <code>enable_shared_from_this</code>. Constructing a <code>shared_ptr</code> to <code>impl</code> takes care of that.</p> 10218</div> 10219</div> 10220<div class="sect2"> 10221<h3 id="techniques_using_shared_ptr_as_a_smart_counted_handle">Using shared_ptr as a smart counted handle</h3> 10222<div class="paragraph"> 10223<p>Some library interfaces use opaque handles, a variation of the <a href="#techniques_incomplete">incomplete class technique</a> described above. An example:</p> 10224</div> 10225<div class="listingblock"> 10226<div class="content"> 10227<pre class="highlight"><code>typedef void * HANDLE; 10228 10229HANDLE CreateProcess(); 10230void CloseHandle(HANDLE);</code></pre> 10231</div> 10232</div> 10233<div class="paragraph"> 10234<p>Instead of a raw pointer, it is possible to use <code>shared_ptr</code> as the handle and get reference counting and automatic resource management for free:</p> 10235</div> 10236<div class="listingblock"> 10237<div class="content"> 10238<pre class="highlight"><code>typedef shared_ptr<void> handle; 10239 10240handle createProcess() 10241{ 10242 shared_ptr<void> pv(CreateProcess(), CloseHandle); 10243 return pv; 10244}</code></pre> 10245</div> 10246</div> 10247</div> 10248<div class="sect2"> 10249<h3 id="techniques_using_shared_ptr_to_execute_code_on_block_exit">Using shared_ptr to execute code on block exit</h3> 10250<div class="paragraph"> 10251<p><code>shared_ptr<void></code> can automatically execute cleanup code when control leaves a scope.</p> 10252</div> 10253<div class="ulist"> 10254<ul> 10255<li> 10256<p>Executing <code>f(p)</code>, where <code>p</code> is a pointer:</p> 10257<div class="listingblock"> 10258<div class="content"> 10259<pre class="highlight"><code>shared_ptr<void> guard(p, f);</code></pre> 10260</div> 10261</div> 10262</li> 10263<li> 10264<p>Executing arbitrary code: <code>f(x, y)</code>:</p> 10265<div class="listingblock"> 10266<div class="content"> 10267<pre class="highlight"><code>shared_ptr<void> guard(static_cast<void*>(0), bind(f, x, y));</code></pre> 10268</div> 10269</div> 10270</li> 10271</ul> 10272</div> 10273</div> 10274<div class="sect2"> 10275<h3 id="techniques_using_shared_ptrvoid_to_hold_an_arbitrary_object">Using shared_ptr<void> to hold an arbitrary object</h3> 10276<div class="paragraph"> 10277<p><code>shared_ptr<void></code> can act as a generic object pointer similar to <code>void*</code>. When a <code>shared_ptr<void></code> instance constructed as:</p> 10278</div> 10279<div class="literalblock"> 10280<div class="content"> 10281<pre>shared_ptr<void> pv(new X);</pre> 10282</div> 10283</div> 10284<div class="paragraph"> 10285<p>is destroyed, it will correctly dispose of the <code>X</code> object by executing <code>~X</code>.</p> 10286</div> 10287<div class="paragraph"> 10288<p>This propery can be used in much the same manner as a raw <code>void*</code> is used to temporarily strip type information from an object pointer. 10289A <code>shared_ptr<void></code> can later be cast back to the correct type by using <code><a href="#shared_ptr_static_pointer_cast">static_pointer_cast</a></code>.</p> 10290</div> 10291</div> 10292<div class="sect2"> 10293<h3 id="techniques_associating_arbitrary_data_with_heterogeneous_shared_ptr_instances">Associating arbitrary data with heterogeneous <code>shared_ptr</code> instances</h3> 10294<div class="paragraph"> 10295<p><code>shared_ptr</code> and <code>weak_ptr</code> support <code>operator<</code> comparisons required by standard associative containers such as <code>std::map</code>. This can be 10296used to non-intrusively associate arbitrary data with objects managed by <code>shared_ptr</code>:</p> 10297</div> 10298<div class="listingblock"> 10299<div class="content"> 10300<pre class="highlight"><code>typedef int Data; 10301 10302std::map<shared_ptr<void>, Data> userData; 10303// or std::map<weak_ptr<void>, Data> userData; to not affect the lifetime 10304 10305shared_ptr<X> px(new X); 10306shared_ptr<int> pi(new int(3)); 10307 10308userData[px] = 42; 10309userData[pi] = 91;</code></pre> 10310</div> 10311</div> 10312</div> 10313<div class="sect2"> 10314<h3 id="techniques_using_shared_ptr_as_a_copyconstructible_mutex_lock">Using <code>shared_ptr</code> as a <code>CopyConstructible</code> mutex lock</h3> 10315<div class="paragraph"> 10316<p>Sometimes it’s necessary to return a mutex lock from a function, and a noncopyable lock cannot be returned by value. It is possible to use <code>shared_ptr</code> as a mutex lock:</p> 10317</div> 10318<div class="listingblock"> 10319<div class="content"> 10320<pre class="highlight"><code>class mutex 10321{ 10322public: 10323 10324 void lock(); 10325 void unlock(); 10326}; 10327 10328shared_ptr<mutex> lock(mutex & m) 10329{ 10330 m.lock(); 10331 return shared_ptr<mutex>(&m, mem_fn(&mutex::unlock)); 10332}</code></pre> 10333</div> 10334</div> 10335<div class="paragraph"> 10336<p>Better yet, the <code>shared_ptr</code> instance acting as a lock can be encapsulated in a dedicated <code>shared_lock</code> class:</p> 10337</div> 10338<div class="listingblock"> 10339<div class="content"> 10340<pre class="highlight"><code>class shared_lock 10341{ 10342private: 10343 10344 shared_ptr<void> pv; 10345 10346public: 10347 10348 template<class Mutex> explicit shared_lock(Mutex & m): pv((m.lock(), &m), mem_fn(&Mutex::unlock)) {} 10349};</code></pre> 10350</div> 10351</div> 10352<div class="paragraph"> 10353<p><code>shared_lock</code> can now be used as:</p> 10354</div> 10355<div class="literalblock"> 10356<div class="content"> 10357<pre>shared_lock lock(m);</pre> 10358</div> 10359</div> 10360<div class="paragraph"> 10361<p>Note that <code>shared_lock</code> is not templated on the mutex type, thanks to <code>shared_ptr<void></code>’s ability to hide type information.</p> 10362</div> 10363</div> 10364<div class="sect2"> 10365<h3 id="techniques_using_shared_ptr_to_wrap_member_function_calls">Using shared_ptr to wrap member function calls</h3> 10366<div class="paragraph"> 10367<p><code>shared_ptr</code> implements the ownership semantics required from the <code>Wrap/CallProxy</code> scheme described in Bjarne Stroustrup’s article 10368"Wrapping C++ Member Function Calls" (available online at <a href="http://www.stroustrup.com/wrapper.pdf" class="bare">http://www.stroustrup.com/wrapper.pdf</a>). An implementation is given below:</p> 10369</div> 10370<div class="listingblock"> 10371<div class="content"> 10372<pre class="highlight"><code>template<class T> class pointer 10373{ 10374private: 10375 10376 T * p_; 10377 10378public: 10379 10380 explicit pointer(T * p): p_(p) 10381 { 10382 } 10383 10384 shared_ptr<T> operator->() const 10385 { 10386 p_->prefix(); 10387 return shared_ptr<T>(p_, mem_fn(&T::suffix)); 10388 } 10389}; 10390 10391class X 10392{ 10393private: 10394 10395 void prefix(); 10396 void suffix(); 10397 friend class pointer<X>; 10398 10399public: 10400 10401 void f(); 10402 void g(); 10403}; 10404 10405int main() 10406{ 10407 X x; 10408 10409 pointer<X> px(&x); 10410 10411 px->f(); 10412 px->g(); 10413}</code></pre> 10414</div> 10415</div> 10416</div> 10417<div class="sect2"> 10418<h3 id="techniques_delayed_deallocation">Delayed deallocation</h3> 10419<div class="paragraph"> 10420<p>In some situations, a single <code>px.reset()</code> can trigger an expensive deallocation in a performance-critical region:</p> 10421</div> 10422<div class="listingblock"> 10423<div class="content"> 10424<pre class="highlight"><code>class X; // ~X is expensive 10425 10426class Y 10427{ 10428 shared_ptr<X> px; 10429 10430public: 10431 10432 void f() 10433 { 10434 px.reset(); 10435 } 10436};</code></pre> 10437</div> 10438</div> 10439<div class="paragraph"> 10440<p>The solution is to postpone the potential deallocation by moving <code>px</code> to a dedicated free list that can be periodically emptied when performance and response times are not an issue:</p> 10441</div> 10442<div class="listingblock"> 10443<div class="content"> 10444<pre class="highlight"><code>vector< shared_ptr<void> > free_list; 10445 10446class Y 10447{ 10448 shared_ptr<X> px; 10449 10450public: 10451 10452 void f() 10453 { 10454 free_list.push_back(px); 10455 px.reset(); 10456 } 10457}; 10458 10459// periodically invoke free_list.clear() when convenient</code></pre> 10460</div> 10461</div> 10462<div class="paragraph"> 10463<p>Another variation is to move the free list logic to the construction point by using a delayed deleter:</p> 10464</div> 10465<div class="listingblock"> 10466<div class="content"> 10467<pre class="highlight"><code>struct delayed_deleter 10468{ 10469 template<class T> void operator()(T * p) 10470 { 10471 try 10472 { 10473 shared_ptr<void> pv(p); 10474 free_list.push_back(pv); 10475 } 10476 catch(...) 10477 { 10478 } 10479 } 10480};</code></pre> 10481</div> 10482</div> 10483</div> 10484<div class="sect2"> 10485<h3 id="techniques_weak_without_shared">Weak pointers to objects not managed by a shared_ptr</h3> 10486<div class="paragraph"> 10487<p>Make the object hold a <code>shared_ptr</code> to itself, using a <code>null_deleter</code>:</p> 10488</div> 10489<div class="listingblock"> 10490<div class="content"> 10491<pre class="highlight"><code>class X 10492{ 10493private: 10494 10495 shared_ptr<X> this_; 10496 int i_; 10497 10498public: 10499 10500 explicit X(int i): this_(this, null_deleter()), i_(i) 10501 { 10502 } 10503 10504 // repeat in all constructors (including the copy constructor!) 10505 10506 X(X const & rhs): this_(this, null_deleter()), i_(rhs.i_) 10507 { 10508 } 10509 10510 // do not forget to not assign this_ in the copy assignment 10511 10512 X & operator=(X const & rhs) 10513 { 10514 i_ = rhs.i_; 10515 } 10516 10517 weak_ptr<X> get_weak_ptr() const { return this_; } 10518};</code></pre> 10519</div> 10520</div> 10521<div class="paragraph"> 10522<p>When the object’s lifetime ends, <code>X::this_</code> will be destroyed, and all weak pointers will automatically expire.</p> 10523</div> 10524</div> 10525</div> 10526</div> 10527<div class="sect1"> 10528<h2 id="history">Appendix B: History and Acknowledgments</h2> 10529<div class="sectionbody"> 10530<div class="sect2"> 10531<h3 id="history_summer_1994">Summer 1994</h3> 10532<div class="paragraph"> 10533<p>Greg Colvin <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/1994/N0555.pdf">proposed</a> 10534to the C++ Standards Committee classes named <code>auto_ptr</code> and <code>counted_ptr</code> which were very 10535similar to what we now call <code>scoped_ptr</code> and <code>shared_ptr</code>. In one of the very few cases 10536where the Library Working Group’s recommendations were not followed by the full committee, 10537<code>counted_ptr</code> was rejected and surprising transfer-of-ownership semantics were added to <code>auto_ptr</code>.</p> 10538</div> 10539</div> 10540<div class="sect2"> 10541<h3 id="history_october_1998">October 1998</h3> 10542<div class="paragraph"> 10543<p>Beman Dawes proposed reviving the original semantics under the names <code>safe_ptr</code> and <code>counted_ptr</code>, 10544meeting of Per Andersson, Matt Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, 10545Dietmar Kühl, Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, the four new class 10546names were finalized, it was decided that there was no need to exactly follow the <code>std::auto_ptr</code> 10547interface, and various function signatures and semantics were finalized.</p> 10548</div> 10549<div class="paragraph"> 10550<p>Over the next three months, several implementations were considered for <code>shared_ptr</code>, and discussed 10551on the <a href="http://www.boost.org/">boost.org</a> mailing list. The implementation questions revolved around 10552the reference count which must be kept, either attached to the pointed to object, or detached elsewhere. 10553Each of those variants have themselves two major variants:</p> 10554</div> 10555<div class="ulist"> 10556<ul> 10557<li> 10558<p>Direct detached: the <code>shared_ptr</code> contains a pointer to the object, and a pointer to the count.</p> 10559</li> 10560<li> 10561<p>Indirect detached: the <code>shared_ptr</code> contains a pointer to a helper object, which in turn contains a pointer to the object and the count.</p> 10562</li> 10563<li> 10564<p>Embedded attached: the count is a member of the object pointed to.</p> 10565</li> 10566<li> 10567<p>Placement attached: the count is attached via operator new manipulations.</p> 10568</li> 10569</ul> 10570</div> 10571<div class="paragraph"> 10572<p>Each implementation technique has advantages and disadvantages. We went so far as to run various timings 10573of the direct and indirect approaches, and found that at least on Intel Pentium chips there was very little 10574measurable difference. Kevlin Henney provided a paper he wrote on "Counted Body Techniques." Dietmar Kühl 10575suggested an elegant partial template specialization technique to allow users to choose which implementation 10576they preferred, and that was also experimented with.</p> 10577</div> 10578<div class="paragraph"> 10579<p>But Greg Colvin and Jerry Schwarz argued that "parameterization will discourage users", and in the end we choose 10580to supply only the direct implementation.</p> 10581</div> 10582</div> 10583<div class="sect2"> 10584<h3 id="history_may_1999">May 1999</h3> 10585<div class="paragraph"> 10586<p>In April and May, 1999, Valentin Bonnard and David Abrahams made a number of suggestions resulting in numerous improvements.</p> 10587</div> 10588</div> 10589<div class="sect2"> 10590<h3 id="history_september_1999">September 1999</h3> 10591<div class="paragraph"> 10592<p>Luis Coelho provided <code>shared_ptr::swap</code> and <code>shared_array::swap</code>.</p> 10593</div> 10594</div> 10595<div class="sect2"> 10596<h3 id="history_november_1999">November 1999</h3> 10597<div class="paragraph"> 10598<p>Darin Adler provided <code>operator ==</code>, <code>operator !=</code>, and <code>std::swap</code> and <code>std::less</code> specializations for shared types.</p> 10599</div> 10600</div> 10601<div class="sect2"> 10602<h3 id="history_may_2001">May 2001</h3> 10603<div class="paragraph"> 10604<p>Vladimir Prus suggested requiring a complete type on destruction. Refinement evolved in discussions including Dave Abrahams, 10605Greg Colvin, Beman Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus, Shankar Sai, and others.</p> 10606</div> 10607</div> 10608<div class="sect2"> 10609<h3 id="history_january_2002">January 2002</h3> 10610<div class="paragraph"> 10611<p>Peter Dimov reworked all four classes, adding features, fixing bugs, splitting them into four separate headers, and adding 10612<code>weak_ptr</code>.</p> 10613</div> 10614</div> 10615<div class="sect2"> 10616<h3 id="history_march_2003">March 2003</h3> 10617<div class="paragraph"> 10618<p>Peter Dimov, Beman Dawes and Greg Colvin <a href="http://open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1450.html">proposed</a> <code>shared_ptr</code> 10619and <code>weak_ptr</code> for inclusion in the Standard Library via the first Library Technical Report (known as TR1). The proposal was 10620accepted and eventually went on to become a part of the C++ standard in its 2011 iteration.</p> 10621</div> 10622</div> 10623<div class="sect2"> 10624<h3 id="history_july_2007">July 2007</h3> 10625<div class="paragraph"> 10626<p>Peter Dimov and Beman Dawes <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm">proposed</a> a number of enhancements 10627to <code>shared_ptr</code> as it was entering the working paper that eventually became the C++11 standard.</p> 10628</div> 10629</div> 10630<div class="sect2"> 10631<h3 id="history_november_2012">November 2012</h3> 10632<div class="paragraph"> 10633<p>Glen Fernandes provided implementations of <code>make_shared</code> and <code>allocate_shared</code> for arrays. They achieve a single allocation 10634for an array that can be initialized with constructor arguments or initializer lists as well as overloads for default initialization 10635and no value initialization.</p> 10636</div> 10637<div class="paragraph"> 10638<p>Peter Dimov aided this development by extending <code>shared_ptr</code> to support arrays via the syntax <code>shared_ptr<T[]></code> and <code>shared_ptr<T[N]></code>.</p> 10639</div> 10640</div> 10641<div class="sect2"> 10642<h3 id="history_april_2013">April 2013</h3> 10643<div class="paragraph"> 10644<p>Peter Dimov <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3640.html">proposed</a> the extension of <code>shared_ptr</code> to support 10645arrays for inclusion into the standard, and it was accepted.</p> 10646</div> 10647</div> 10648<div class="sect2"> 10649<h3 id="history_february_2014">February 2014</h3> 10650<div class="paragraph"> 10651<p>Glen Fernandes updated <code>make_shared</code> and <code>allocate_shared</code> to conform to the specification in C++ standard paper 10652<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3870.html">N3870</a>, and implemented <code>make_unique</code> for arrays and objects.</p> 10653</div> 10654<div class="paragraph"> 10655<p>Peter Dimov and Glen Fernandes updated the scalar and array implementations, respectively, to resolve C++ standard library defect 2070.</p> 10656</div> 10657</div> 10658<div class="sect2"> 10659<h3 id="history_february_2017">February 2017</h3> 10660<div class="paragraph"> 10661<p>Glen Fernandes rewrote <code>allocate_shared</code> and <code>make_shared</code> for arrays for a more optimal and more maintainable implementation.</p> 10662</div> 10663</div> 10664<div class="sect2"> 10665<h3 id="history_june_2017">June 2017</h3> 10666<div class="paragraph"> 10667<p>Peter Dimov and Glen Fernandes rewrote the documentation in Asciidoc format.</p> 10668</div> 10669<div class="paragraph"> 10670<p>Peter Dimov added <code>atomic_shared_ptr</code> and <code>local_shared_ptr</code>.</p> 10671</div> 10672</div> 10673<div class="sect2"> 10674<h3 id="history_august_2019">August 2019</h3> 10675<div class="paragraph"> 10676<p>Glen Fernandes implemented <code>allocate_unique</code> for scalars and arrays.</p> 10677</div> 10678</div> 10679</div> 10680</div> 10681<div class="sect1"> 10682<h2 id="shared_array">Appendix C: shared_array (deprecated)</h2> 10683<div class="sectionbody"> 10684<div class="admonitionblock note"> 10685<table> 10686<tr> 10687<td class="icon"> 10688<div class="title">Note</div> 10689</td> 10690<td class="content"> 10691This facility is deprecated because a <code>shared_ptr</code> to <code>T[]</code> or <code>T[N]</code> 10692is now available, and is superior in every regard. 10693</td> 10694</tr> 10695</table> 10696</div> 10697<div class="sect2"> 10698<h3 id="shared_array_description">Description</h3> 10699<div class="paragraph"> 10700<p>The <code>shared_array</code> class template stores a pointer to a dynamically allocated 10701array. (Dynamically allocated array are allocated with the C++ <code>new[]</code> 10702expression.) The object pointed to is guaranteed to be deleted when the last 10703<code>shared_array</code> pointing to it is destroyed or reset.</p> 10704</div> 10705<div class="paragraph"> 10706<p>Every <code>shared_array</code> meets the <em>CopyConstructible</em> and <em>Assignable</em> 10707requirements of the C++ Standard Library, and so can be used in standard 10708library containers. Comparison operators are supplied so that shared_array 10709works with the standard library’s associative containers.</p> 10710</div> 10711<div class="paragraph"> 10712<p>Normally, a <code>shared_array</code> cannot correctly hold a pointer to an object that 10713has been allocated with the non-array form of <code>new</code>. See <code>shared_ptr</code> for that 10714usage.</p> 10715</div> 10716<div class="paragraph"> 10717<p>Because the implementation uses reference counting, cycles of <code>shared_array</code> 10718instances will not be reclaimed. For example, if <code>main</code> holds a shared_array 10719to <code>A</code>, which directly or indirectly holds a shared_array back to <code>A</code>, the use 10720count of <code>A</code> will be 2. Destruction of the original <code>shared_array</code> will leave 10721<code>A</code> dangling with a use count of 1.</p> 10722</div> 10723<div class="paragraph"> 10724<p>A <code>shared_ptr</code> to a <code>std::vector</code> is an alternative to a <code>shared_array</code> that 10725is a bit heavier duty but far more flexible.</p> 10726</div> 10727<div class="paragraph"> 10728<p>The class template is parameterized on <code>T</code>, the type of the object pointed to. 10729<code>shared_array</code> and most of its member functions place no requirements on <code>T</code>; 10730it is allowed to be an incomplete type, or <code>void</code>. Member functions that do 10731place additional requirements (constructors, reset) are explicitly documented 10732below.</p> 10733</div> 10734</div> 10735<div class="sect2"> 10736<h3 id="shared_array_synopsis">Synopsis</h3> 10737<div class="listingblock"> 10738<div class="content"> 10739<pre class="highlight"><code>namespace boost { 10740 10741 template<class T> class shared_array { 10742 public: 10743 typedef T element_type; 10744 10745 explicit shared_array(T* p = 0); 10746 template<class D> shared_array(T* p, D d); 10747 shared_array(const shared_array& v) noexcept; 10748 10749 ~shared_array() noexcept; 10750 10751 shared_array& operator=(const shared_array& v) noexcept; 10752 10753 void reset(T* p = 0); 10754 template<class D> void reset(T* p, D d); 10755 10756 T& operator[](std::ptrdiff_t n) const noexcept; 10757 T* get() const noexcept; 10758 10759 bool unique() const noexcept; 10760 long use_count() const noexcept; 10761 10762 explicit operator bool() const noexcept; 10763 10764 void swap(shared_array<T>& v) noexcept; 10765 }; 10766 10767 template<class T> bool 10768 operator==(const shared_array<T>& a, const shared_array<T>& b) noexcept; 10769 template<class T> bool 10770 operator!=(const shared_array<T>& a, const shared_array<T>& b) noexcept; 10771 template<class T> bool 10772 operator<(const shared_array<T>& a, const shared_array<T>& b) noexcept; 10773 10774 template<class T> 10775 void swap(shared_array<T>& a, shared_array<T>& b) noexcept; 10776}</code></pre> 10777</div> 10778</div> 10779</div> 10780<div class="sect2"> 10781<h3 id="shared_array_members">Members</h3> 10782<div class="sect3"> 10783<h4 id="shared_array_element_type">element_type</h4> 10784<div class="listingblock"> 10785<div class="content"> 10786<pre class="highlight"><code>typedef T element_type;</code></pre> 10787</div> 10788</div> 10789<div class="dlist"> 10790<dl> 10791<dt class="hdlist1">Type</dt> 10792<dd> 10793<p>Provides the type of the stored pointer.</p> 10794</dd> 10795</dl> 10796</div> 10797</div> 10798<div class="sect3"> 10799<h4 id="shared_array_constructors">Constructors</h4> 10800<div class="listingblock"> 10801<div class="content"> 10802<pre class="highlight"><code>explicit shared_array(T* p = 0);</code></pre> 10803</div> 10804</div> 10805<div class="ulist none"> 10806<ul class="none"> 10807<li> 10808<p></p> 10809<div class="dlist"> 10810<dl> 10811<dt class="hdlist1">Effects</dt> 10812<dd> 10813<p>Constructs a <code>shared_array</code>, storing a copy of <code>p</code>, which must be a 10814pointer to an array that was allocated via a C++ <code>new[]</code> expression or be 0. 10815Afterwards, the use count is 1 (even if <code>p == 0</code>; see <code>~shared_array</code>).</p> 10816</dd> 10817<dt class="hdlist1">Requires</dt> 10818<dd> 10819<p><code>T</code> is a complete type.</p> 10820</dd> 10821<dt class="hdlist1">Throws</dt> 10822<dd> 10823<p><code>std::bad_alloc</code>. If an exception is thrown, <code>delete[] p</code> is called.</p> 10824</dd> 10825</dl> 10826</div> 10827</li> 10828</ul> 10829</div> 10830<div class="listingblock"> 10831<div class="content"> 10832<pre class="highlight"><code>template<class D> shared_array(T* p, D d);</code></pre> 10833</div> 10834</div> 10835<div class="ulist none"> 10836<ul class="none"> 10837<li> 10838<p></p> 10839<div class="dlist"> 10840<dl> 10841<dt class="hdlist1">Effects</dt> 10842<dd> 10843<p>Constructs a <code>shared_array</code>, storing a copy of <code>p</code> and of <code>d</code>. 10844Afterwards, the use count is 1. When the the time comes to delete the array 10845pointed to by <code>p</code>, the object <code>d</code> is used in the statement <code>d(p)</code>.</p> 10846</dd> 10847<dt class="hdlist1">Requires</dt> 10848</dl> 10849</div> 10850</li> 10851<li> 10852<p><code>T</code> is a complete type.</p> 10853</li> 10854<li> 10855<p>The copy constructor and destructor of <code>D</code> must not throw.</p> 10856</li> 10857<li> 10858<p>Invoking the object <code>d</code> with parameter <code>p</code> must not throw.</p> 10859<div class="dlist"> 10860<dl> 10861<dt class="hdlist1">Throws</dt> 10862<dd> 10863<p><code>std::bad_alloc</code>. If an exception is thrown, <code>d(p)</code> is called.</p> 10864</dd> 10865</dl> 10866</div> 10867</li> 10868</ul> 10869</div> 10870<div class="listingblock"> 10871<div class="content"> 10872<pre class="highlight"><code>shared_array(const shared_array& v) noexcept;</code></pre> 10873</div> 10874</div> 10875<div class="ulist none"> 10876<ul class="none"> 10877<li> 10878<p></p> 10879<div class="dlist"> 10880<dl> 10881<dt class="hdlist1">Effects</dt> 10882<dd> 10883<p>Constructs a <code>shared_array</code>, as if by storing a copy of the pointer 10884stored in <code>v</code>. Afterwards, the use count for all copies is 1 more than the 10885initial use count.</p> 10886</dd> 10887<dt class="hdlist1">Requires</dt> 10888<dd> 10889<p><code>T</code> is a complete type.</p> 10890</dd> 10891</dl> 10892</div> 10893</li> 10894</ul> 10895</div> 10896</div> 10897<div class="sect3"> 10898<h4 id="shared_array_destructor">Destructor</h4> 10899<div class="listingblock"> 10900<div class="content"> 10901<pre class="highlight"><code>~shared_array() noexcept;</code></pre> 10902</div> 10903</div> 10904<div class="ulist none"> 10905<ul class="none"> 10906<li> 10907<p></p> 10908<div class="dlist"> 10909<dl> 10910<dt class="hdlist1">Effects</dt> 10911<dd> 10912<p>Decrements the use count. Then, if the use count is 0, deletes the 10913array pointed to by the stored pointer. Note that <code>delete[]</code> on a pointer with 10914a value of 0 is harmless.</p> 10915</dd> 10916</dl> 10917</div> 10918</li> 10919</ul> 10920</div> 10921</div> 10922<div class="sect3"> 10923<h4 id="shared_array_assignment">Assignment</h4> 10924<div class="listingblock"> 10925<div class="content"> 10926<pre class="highlight"><code>shared_array& operator=(const shared_array& v) noexcept;</code></pre> 10927</div> 10928</div> 10929<div class="ulist none"> 10930<ul class="none"> 10931<li> 10932<p></p> 10933<div class="dlist"> 10934<dl> 10935<dt class="hdlist1">Effects</dt> 10936<dd> 10937<p>Constructs a new <code>shared_array</code> as described above, then replaces 10938this <code>shared_array</code> with the new one, destroying the replaced object.</p> 10939</dd> 10940<dt class="hdlist1">Requires</dt> 10941<dd> 10942<p><code>T</code> is a complete type.</p> 10943</dd> 10944<dt class="hdlist1">Returns</dt> 10945<dd> 10946<p><code>*this</code>.</p> 10947</dd> 10948</dl> 10949</div> 10950</li> 10951</ul> 10952</div> 10953</div> 10954<div class="sect3"> 10955<h4 id="shared_array_reset">reset</h4> 10956<div class="listingblock"> 10957<div class="content"> 10958<pre class="highlight"><code>void reset(T* p = 0);</code></pre> 10959</div> 10960</div> 10961<div class="ulist none"> 10962<ul class="none"> 10963<li> 10964<p></p> 10965<div class="dlist"> 10966<dl> 10967<dt class="hdlist1">Effects</dt> 10968<dd> 10969<p>Constructs a new <code>shared_array</code> as described above, then replaces 10970this <code>shared_array</code> with the new one, destroying the replaced object.</p> 10971</dd> 10972<dt class="hdlist1">Requires</dt> 10973<dd> 10974<p><code>T</code> is a complete type.</p> 10975</dd> 10976<dt class="hdlist1">Throws</dt> 10977<dd> 10978<p><code>std::bad_alloc</code>. If an exception is thrown, <code>delete[] p</code> is called.</p> 10979</dd> 10980</dl> 10981</div> 10982</li> 10983</ul> 10984</div> 10985<div class="listingblock"> 10986<div class="content"> 10987<pre class="highlight"><code>template<class D> void reset(T* p, D d);</code></pre> 10988</div> 10989</div> 10990<div class="ulist none"> 10991<ul class="none"> 10992<li> 10993<p></p> 10994<div class="dlist"> 10995<dl> 10996<dt class="hdlist1">Effects</dt> 10997<dd> 10998<p>Constructs a new <code>shared_array</code> as described above, then replaces 10999this <code>shared_array</code> with the new one, destroying the replaced object.</p> 11000</dd> 11001<dt class="hdlist1">Requires</dt> 11002</dl> 11003</div> 11004</li> 11005<li> 11006<p><code>T</code> is a complete type.</p> 11007</li> 11008<li> 11009<p>The copy constructor of <code>D</code> must not throw.</p> 11010<div class="dlist"> 11011<dl> 11012<dt class="hdlist1">Throws</dt> 11013<dd> 11014<p><code>std::bad_alloc</code>. If an exception is thrown, <code>d(p)</code> is called.</p> 11015</dd> 11016</dl> 11017</div> 11018</li> 11019</ul> 11020</div> 11021</div> 11022<div class="sect3"> 11023<h4 id="shared_array_indexing">Indexing</h4> 11024<div class="listingblock"> 11025<div class="content"> 11026<pre class="highlight"><code>T& operator[](std::ptrdiff_t n) const noexcept;</code></pre> 11027</div> 11028</div> 11029<div class="dlist"> 11030<dl> 11031<dt class="hdlist1">Returns</dt> 11032<dd> 11033<p>A reference to element <code>n</code> of the array pointed to by the stored 11034pointer. Behavior is undefined and almost certainly undesirable if the stored 11035pointer is 0, or if <code>n</code> is less than 0 or is greater than or equal to the 11036number of elements in the array.</p> 11037</dd> 11038<dt class="hdlist1">Requires</dt> 11039<dd> 11040<p><code>T</code> is a complete type.</p> 11041</dd> 11042</dl> 11043</div> 11044</div> 11045<div class="sect3"> 11046<h4 id="shared_array_get">get</h4> 11047<div class="listingblock"> 11048<div class="content"> 11049<pre class="highlight"><code>T* get() const noexcept;</code></pre> 11050</div> 11051</div> 11052<div class="ulist none"> 11053<ul class="none"> 11054<li> 11055<p></p> 11056<div class="dlist"> 11057<dl> 11058<dt class="hdlist1">Returns</dt> 11059<dd> 11060<p>The stored pointer.</p> 11061</dd> 11062</dl> 11063</div> 11064</li> 11065</ul> 11066</div> 11067</div> 11068<div class="sect3"> 11069<h4 id="shared_array_unique">unique</h4> 11070<div class="listingblock"> 11071<div class="content"> 11072<pre class="highlight"><code>bool unique() const noexcept;</code></pre> 11073</div> 11074</div> 11075<div class="ulist none"> 11076<ul class="none"> 11077<li> 11078<p></p> 11079<div class="dlist"> 11080<dl> 11081<dt class="hdlist1">Returns</dt> 11082<dd> 11083<p><code>true</code> if no other <code>shared_array</code> is sharing ownership of the 11084stored pointer, <code>false</code> otherwise.</p> 11085</dd> 11086</dl> 11087</div> 11088</li> 11089</ul> 11090</div> 11091</div> 11092<div class="sect3"> 11093<h4 id="shared_array_use_count">use_count</h4> 11094<div class="listingblock"> 11095<div class="content"> 11096<pre class="highlight"><code>long use_count() const noexcept;</code></pre> 11097</div> 11098</div> 11099<div class="ulist none"> 11100<ul class="none"> 11101<li> 11102<p></p> 11103<div class="dlist"> 11104<dl> 11105<dt class="hdlist1">Returns</dt> 11106<dd> 11107<p>The number of <code>shared_array</code> objects sharing ownership of the 11108stored pointer.</p> 11109</dd> 11110</dl> 11111</div> 11112</li> 11113</ul> 11114</div> 11115</div> 11116<div class="sect3"> 11117<h4 id="shared_array_conversions">Conversions</h4> 11118<div class="listingblock"> 11119<div class="content"> 11120<pre class="highlight"><code>explicit operator bool() const noexcept;</code></pre> 11121</div> 11122</div> 11123<div class="ulist none"> 11124<ul class="none"> 11125<li> 11126<p></p> 11127<div class="dlist"> 11128<dl> 11129<dt class="hdlist1">Returns</dt> 11130<dd> 11131<p><code>get() != 0</code>.</p> 11132</dd> 11133<dt class="hdlist1">Requires</dt> 11134<dd> 11135<p><code>T</code> is a complete type.</p> 11136</dd> 11137</dl> 11138</div> 11139</li> 11140</ul> 11141</div> 11142</div> 11143<div class="sect3"> 11144<h4 id="shared_array_swap">swap</h4> 11145<div class="listingblock"> 11146<div class="content"> 11147<pre class="highlight"><code>void swap(shared_array<T>& b) noexcept;</code></pre> 11148</div> 11149</div> 11150<div class="ulist none"> 11151<ul class="none"> 11152<li> 11153<p></p> 11154<div class="dlist"> 11155<dl> 11156<dt class="hdlist1">Effects</dt> 11157<dd> 11158<p>Exchanges the contents of the two smart pointers.</p> 11159</dd> 11160</dl> 11161</div> 11162</li> 11163</ul> 11164</div> 11165</div> 11166</div> 11167<div class="sect2"> 11168<h3 id="shared_array_free_functions">Free Functions</h3> 11169<div class="sect3"> 11170<h4 id="shared_array_comparison">Comparison</h4> 11171<div class="listingblock"> 11172<div class="content"> 11173<pre class="highlight"><code>template<class T> bool 11174 operator==(const shared_array<T>& a, const shared_array<T>& b) noexcept;</code></pre> 11175</div> 11176</div> 11177<div class="listingblock"> 11178<div class="content"> 11179<pre class="highlight"><code>template<class T> bool 11180 operator!=(const shared_array<T>& a, const shared_array<T>& b) noexcept;</code></pre> 11181</div> 11182</div> 11183<div class="listingblock"> 11184<div class="content"> 11185<pre class="highlight"><code>template<class T> bool 11186 operator<(const shared_array<T>& a, const shared_array<T>& b) noexcept;</code></pre> 11187</div> 11188</div> 11189<div class="ulist none"> 11190<ul class="none"> 11191<li> 11192<p></p> 11193<div class="dlist"> 11194<dl> 11195<dt class="hdlist1">Returns</dt> 11196<dd> 11197<p>The result of comparing the stored pointers of the two smart 11198pointers.</p> 11199</dd> 11200</dl> 11201</div> 11202</li> 11203</ul> 11204</div> 11205<div class="admonitionblock note"> 11206<table> 11207<tr> 11208<td class="icon"> 11209<div class="title">Note</div> 11210</td> 11211<td class="content"> 11212The <code>operator<</code> overload is provided to define an ordering so that 11213<code>shared_array</code> objects can be used in associative containers such as 11214<code>std::map</code>. The implementation uses <code>std::less<T*></code> to perform the comparison. 11215This ensures that the comparison is handled correctly, since the standard 11216mandates that relational operations on pointers are unspecified (5.9 11217[expr.rel] paragraph 2) but <code>std::less</code> on pointers is well-defined (20.3.3 11218[lib.comparisons] paragraph 8). 11219</td> 11220</tr> 11221</table> 11222</div> 11223</div> 11224<div class="sect3"> 11225<h4 id="shared_array_swap_2">swap</h4> 11226<div class="listingblock"> 11227<div class="content"> 11228<pre class="highlight"><code>template<class T> 11229 void swap(shared_array<T>& a, shared_array<T>& b) noexcept;</code></pre> 11230</div> 11231</div> 11232<div class="ulist none"> 11233<ul class="none"> 11234<li> 11235<p></p> 11236<div class="dlist"> 11237<dl> 11238<dt class="hdlist1">Returns</dt> 11239<dd> 11240<p><code>a.swap(b)</code>.</p> 11241</dd> 11242<dt class="hdlist1">Requires</dt> 11243<dd> 11244<p><code>T</code> is a complete type.</p> 11245</dd> 11246</dl> 11247</div> 11248</li> 11249</ul> 11250</div> 11251</div> 11252</div> 11253</div> 11254</div> 11255<div class="sect1"> 11256<h2 id="copyright">Appendix D: Copyright and License</h2> 11257<div class="sectionbody"> 11258<div class="paragraph"> 11259<p>This documentation is</p> 11260</div> 11261<div class="ulist"> 11262<ul> 11263<li> 11264<p>Copyright 1999 Greg Colvin</p> 11265</li> 11266<li> 11267<p>Copyright 1999 Beman Dawes</p> 11268</li> 11269<li> 11270<p>Copyright 2002 Darin Adler</p> 11271</li> 11272<li> 11273<p>Copyright 2003-2020 Peter Dimov</p> 11274</li> 11275<li> 11276<p>Copyright 2005, 2006 Ion Gaztañaga</p> 11277</li> 11278<li> 11279<p>Copyright 2008 Frank Mori Hess</p> 11280</li> 11281<li> 11282<p>Copyright 2012-2017 Glen Fernandes</p> 11283</li> 11284<li> 11285<p>Copyright 2013 Andrey Semashev</p> 11286</li> 11287</ul> 11288</div> 11289<div class="paragraph"> 11290<p>and is distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</p> 11291</div> 11292</div> 11293</div> 11294</div> 11295<div id="footer"> 11296<div id="footer-text"> 11297Last updated 2020-08-11 14:57:11 UTC 11298</div> 11299</div> 11300<style> 11301 11302*:not(pre)>code { background: none; color: #600000; } 11303:not(pre):not([class^=L])>code { background: none; color: #600000; } 11304table tr.even, table tr.alt, table tr:nth-of-type(even) { background: none; } 11305 11306</style> 11307</body> 11308</html>