Classe `shared_ptr`

Article
06/16/2023

Encapsule un pointeur intelligent contenant des références autour d'un objet alloué dynamiquement.

Syntaxe

template <class T>
class shared_ptr;

Notes

La shared_ptr classe décrit un objet qui utilise le comptage de références pour gérer les ressources. Un objet shared_ptr contient en fait un pointeur vers la ressource qu'il possède ou contient un pointeur null. Une ressource peut être détenue par plusieurs objets shared_ptr. Quand le dernier objet shared_ptr qui possède une ressource particulière est détruit, la ressource est libérée.

Un shared_ptr arrêt de la propriété d’une ressource lorsqu’elle est réaffectée ou réinitialisée.

L'argument de modèle T peut être un type incomplet, sauf comme mentionné pour certaines fonctions membres.

Quand un objet shared_ptr<T> est construit à partir d'un pointeur de ressource de type G* ou à partir d'un shared_ptr<G>, le type de pointeur G* doit être convertible en T*. S’il n’est pas convertible, le code ne sera pas compilé. Par exemple :

#include <memory>
using namespace std;

class F {};
class G : public F {};

shared_ptr<G> sp0(new G);   // okay, template parameter G and argument G*
shared_ptr<G> sp1(sp0);     // okay, template parameter G and argument shared_ptr<G>
shared_ptr<F> sp2(new G);   // okay, G* convertible to F*
shared_ptr<F> sp3(sp0);     // okay, template parameter F and argument shared_ptr<G>
shared_ptr<F> sp4(sp2);     // okay, template parameter F and argument shared_ptr<F>
shared_ptr<int> sp5(new G); // error, G* not convertible to int*
shared_ptr<int> sp6(sp2);   // error, template parameter int and argument shared_ptr<F>

Un objet shared_ptr possède une ressource :

s'il a été construit avec un pointeur vers cette ressource ;
s'il a été construit à partir d'un objet shared_ptr qui possède cette ressource ;
s’il a été construit à partir d’un weak_ptr objet qui pointe vers cette ressource, ou
si la propriété de cette ressource a été affectée, avec shared_ptr::operator= ou en appelant la fonction shared_ptr::resetmembre.

Les objets shared_ptr qui sont propriétaires d'une ressource partagent un bloc de contrôle. Le bloc de contrôle contient :

le nombre d'objets shared_ptr qui sont propriétaires de la ressource ;
le nombre d'objets weak_ptr qui pointent vers la ressource ;
le suppresseur de cette ressource, le cas échéant ;
l'allocateur personnalisé pour le bloc de contrôle, le cas échéant.

Un shared_ptr objet initialisé à l’aide d’un pointeur Null a un bloc de contrôle et n’est pas vide. Une fois qu'un objet shared_ptr a libéré une ressource, il n'en est plus propriétaire. Une fois qu'un objet weak_ptr a libéré une ressource, il ne pointe plus vers cette ressource.

Quand le nombre d'objets shared_ptr propriétaires d'une ressource devient égal à zéro, la ressource est libérée, soit en étant supprimée, soit en passant son adresse à un suppresseur, selon la façon dont la propriété de la ressource a été créée initialement. Quand le nombre d'objets shared_ptr propriétaires d'une ressource est égal à zéro et que le nombre d'objets weak_ptr qui pointent vers cette ressource est égal à zéro, le bloc de contrôle est libéré, à l'aide de l'allocateur personnalisé du bloc de contrôle s'il en a un.

Un objet vide shared_ptr ne possède aucune ressource et n’a aucun bloc de contrôle.

Un suppresseur est un objet de fonction qui a une fonction membre operator(). Son type doit être constructible par copie et son constructeur de copie et son destructeur ne doivent pas lever d'exceptions. Il accepte un paramètre, l'objet à supprimer.

Certaines fonctions acceptent une liste d'arguments qui définit les propriétés de l'objet shared_ptr<T> ou weak_ptr<T> résultant. Vous pouvez spécifier une telle liste d'arguments de plusieurs façons :

aucun argument : l’objet résultant est un objet vide shared_ptr ou un objet vide weak_ptr .

ptr: pointeur de type Other* vers la ressource à gérer. T doit être un type complet. Si la fonction échoue (car le bloc de contrôle ne peut pas être alloué), elle évalue l’expression delete ptr.

ptr, deleter: pointeur de type Other* vers la ressource à gérer et supprimer pour cette ressource. Si la fonction échoue (car le bloc de contrôle ne peut pas être alloué), il appelle deleter(ptr), qui doit être bien défini.

ptr, deleter, alloc: pointeur de type Other* vers la ressource à gérer, un deleter pour cette ressource et un allocateur pour gérer tout stockage qui doit être alloué et libéré. Si la fonction échoue (car le bloc de contrôle ne peut pas être alloué), il appelle deleter(ptr), qui doit être bien défini.

sp: objet shared_ptr<Other> qui possède la ressource à gérer.

wp: objet weak_ptr<Other> qui pointe vers la ressource à gérer.

ap: objet auto_ptr<Other> qui contient un pointeur vers la ressource à gérer. Si la fonction réussit, elle appelle ap.release(); sinon elle reste ap inchangée.

Dans tous les cas, le type de pointeur Other* doit être convertible en T*.

Cohérence de thread

Plusieurs threads peuvent lire et écrire différents objets shared_ptr simultanément, même quand les objets sont des copies qui partagent la propriété.

Membres

Nom	Description
Constructeurs
`shared_ptr`	Construit un objet `shared_ptr`.
`~shared_ptr`	Détruit un `shared_ptr`.
Typedefs
`element_type`	Type d’un élément.
`weak_type`	Type d’un pointeur faible vers un élément.
Fonctions membres
`get`	Obtient l'adresse de la ressource détenue.
`owner_before`	Retourne true si ce `shared_ptr` est classé avant le pointeur fourni (ou est inférieur à celui-ci).
`reset`	Remplacer la ressource détenue.
`swap`	Échange deux objets `shared_ptr`.
`unique`	Teste si la ressource détenue est unique.
`use_count`	Compte le nombre de propriétaires de ressources.
Opérateurs
`operator bool`	Teste si une ressource détenue existe.
`operator*`	Obtient la valeur désignée.
`operator=`	Remplace la ressource détenue.
`operator->`	Obtient un pointeur vers la valeur désignée.

`element_type`

Type d’un élément.

typedef T element_type;                  // before C++17
using element_type = remove_extent_t<T>; // C++17

Notes

Le element_type type est un synonyme du paramètre Tde modèle.

Exemple

// std__memory__shared_ptr_element_type.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp0(new int(5));
    std::shared_ptr<int>::element_type val = *sp0;

    std::cout << "*sp0 == " << val << std::endl;

    return (0);
}

*sp0 == 5

`get`

Obtient l'adresse de la ressource détenue.

element_type* get() const noexcept;

Notes

La fonction membre retourne l’adresse de la ressource détenue. Si l’objet ne possède pas de ressource, il retourne 0.

Exemple

// std__memory__shared_ptr_get.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp0;
    std::shared_ptr<int> sp1(new int(5));

    std::cout << "sp0.get() == 0 == " << std::boolalpha
        << (sp0.get() == 0) << std::endl;
    std::cout << "*sp1.get() == " << *sp1.get() << std::endl;

    return (0);
}

sp0.get() == 0 == true
*sp1.get() == 5

`operator bool`

Teste si une ressource détenue existe.

explicit operator bool() const noexcept;

Notes

L’opérateur retourne une valeur de true quand get() != nullptr, sinon false.

Exemple

// std__memory__shared_ptr_operator_bool.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp0;
    std::shared_ptr<int> sp1(new int(5));

    std::cout << "(bool)sp0 == " << std::boolalpha
        << (bool)sp0 << std::endl;
    std::cout << "(bool)sp1 == " << std::boolalpha
        << (bool)sp1 << std::endl;

    return (0);
}

(bool)sp0 == false
(bool)sp1 == true

`operator*`

Obtient la valeur désignée.

T& operator*() const noexcept;

Notes

L’opérateur d’indirection retourne *get(). Par conséquent, le pointeur stocké ne doit pas être null.

Exemple

// std__memory__shared_ptr_operator_st.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp0(new int(5));

    std::cout << "*sp0 == " << *sp0 << std::endl;

    return (0);
}

*sp0 == 5

`operator=`

Remplace la ressource détenue.

shared_ptr& operator=(const shared_ptr& sp) noexcept;

shared_ptr& operator=(shared_ptr&& sp) noexcept;

template <class Other>
shared_ptr& operator=(const shared_ptr<Other>& sp) noexcept;

template <class Other>
shared_ptr& operator=(shared_ptr<Other>&& sp) noexcept;

template <class Other>
shared_ptr& operator=(auto_ptr<Other>&& ap);    // deprecated in C++11, removed in C++17

template <class Other, class Deleter>
shared_ptr& operator=(unique_ptr<Other, Deleter>&& up);

Paramètres

sp
Pointeur partagé à partir duquel copier ou passer.

ap
Pointeur automatique à déplacer. La auto_ptr surcharge est déconseillée en C++11 et supprimée en C++17.

up
Pointeur unique vers l’objet à adopter la propriété. up ne possède aucun objet après l’appel.

Other
Type de l’objet pointé par sp, apou up.

Deleter
Type du deleter de l’objet appartenant, stocké pour la suppression ultérieure de l’objet.

Notes

Tous les opérateurs décrémentent le nombre de références pour la ressource actuellement détenue par *this et assignent la propriété de la ressource nommée par la séquence d’opérandes à *this. Si le nombre de références atteint zéro, la ressource est libérée. En cas d’échec d’un opérateur, il reste *this inchangé.

Exemple

// std__memory__shared_ptr_operator_as.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp0;
    std::shared_ptr<int> sp1(new int(5));
    std::unique_ptr<int> up(new int(10));

    sp0 = sp1;
    std::cout << "*sp0 == " << *sp0 << std::endl;

    sp0 = up;
    std::cout << "*sp0 == " << *sp0 << std::endl;

    return (0);
}

*sp0 == 5
*sp0 == 10

`operator->`

Obtient un pointeur vers la valeur désignée.

T* operator->() const noexcept;

Notes

L’opérateur de sélection retourne get() de sorte que l’expression sp->member se comporte comme (sp.get())->member, où sp est un objet de la classe shared_ptr<T>. Le pointeur stocké ne doit donc pas être Null, et T doit être une classe, une structure ou une union avec un membre member.

Exemple

// std__memory__shared_ptr_operator_ar.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

typedef std::pair<int, int> Mypair;
int main()
{
    std::shared_ptr<Mypair> sp0(new Mypair(1, 2));

    std::cout << "sp0->first == " << sp0->first << std::endl;
    std::cout << "sp0->second == " << sp0->second << std::endl;

    return (0);
}

sp0->first == 1
sp0->second == 2

`owner_before`

Retourne true si ce shared_ptr est classé avant le pointeur fourni (ou est inférieur à celui-ci).

template <class Other>
bool owner_before(const shared_ptr<Other>& ptr) const noexcept;

template <class Other>
bool owner_before(const weak_ptr<Other>& ptr) const noexcept;

Paramètres

ptr
Référence lvalue à un shared_ptr ou un weak_ptr.

Notes

La fonction membre du modèle retourne la valeur true si *this elle est ordonnée avant ptr.

`reset`

Remplacer la ressource détenue.

void reset() noexcept;

template <class Other>
void reset(Other *ptr);

template <class Other, class Deleter>
void reset(
    Other *ptr,
    Deleter deleter);

template <class Other, class Deleter, class Allocator>
void reset(
    Other *ptr,
    Deleter deleter,
    Allocator alloc);

Paramètres

Other
Type contrôlé par le pointeur d’argument.

Deleter
Type du suppresseur.

ptr
Pointeur à copier.

deleter
Suppresseur à copier.

Allocator
Type de l'allocateur.

alloc
Allocateur à copier.

Notes

Exemple

// std__memory__shared_ptr_reset.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

struct deleter
{
    void operator()(int *p)
    {
        delete p;
    }
};

int main()
{
    std::shared_ptr<int> sp(new int(5));

    std::cout << "*sp == " << std::boolalpha
        << *sp << std::endl;

    sp.reset();
    std::cout << "(bool)sp == " << std::boolalpha
        << (bool)sp << std::endl;

    sp.reset(new int(10));
    std::cout << "*sp == " << std::boolalpha
        << *sp << std::endl;

    sp.reset(new int(15), deleter());
    std::cout << "*sp == " << std::boolalpha
        << *sp << std::endl;

    return (0);
}

*sp == 5
(bool)sp == false
*sp == 10
*sp == 15

`shared_ptr`

Construit un objet shared_ptr.

constexpr shared_ptr() noexcept;

constexpr shared_ptr(nullptr_t) noexcept : shared_ptr() {}

shared_ptr(const shared_ptr& sp) noexcept;

shared_ptr(shared_ptr&& sp) noexcept;

template <class Other>
explicit shared_ptr(Other* ptr);

template <class Other, class Deleter>
shared_ptr(
    Other* ptr,
    Deleter deleter);

template <class Deleter>
shared_ptr(
    nullptr_t ptr,
    Deleter deleter);

template <class Other, class Deleter, class Allocator>
shared_ptr(
    Other* ptr,
    Deleter deleter,
    Allocator alloc);

template <class Deleter, class Allocator>
shared_ptr(
    nullptr_t ptr,
    Deleter deleter,
    Allocator alloc);

template <class Other>
shared_ptr(
    const shared_ptr<Other>& sp) noexcept;

template <class Other>
explicit shared_ptr(
    const weak_ptr<Other>& wp);

template <class &>
shared_ptr(
    std::auto_ptr<Other>& ap);

template <class &>
shared_ptr(
    std::auto_ptr<Other>&& ap);

template <class Other, class Deleter>
shared_ptr(
    unique_ptr<Other, Deleter>&& up);

template <class Other>
shared_ptr(
    const shared_ptr<Other>& sp,
    element_type* ptr) noexcept;

template <class Other>
shared_ptr(
    shared_ptr<Other>&& sp,
    element_type* ptr) noexcept;

template <class Other, class Deleter>
shared_ptr(
    const unique_ptr<Other, Deleter>& up) = delete;

Paramètres

Other
Type contrôlé par le pointeur d’argument.

ptr
Pointeur à copier.

Deleter
Type du suppresseur.

Allocator
Type de l'allocateur.

deleter
Suppresseur.

alloc
Allocateur.

sp
Pointeur intelligent à copier.

wp
Pointeur faible.

ap
Pointeur automatique à copier.

Notes

Chaque constructeur construit un objet qui possède la ressource nommée par la séquence d’opérandes. Le constructeur shared_ptr(const weak_ptr<Other>& wp) lève un objet d’exception de type bad_weak_ptr si wp.expired().

Exemple

// std__memory__shared_ptr_construct.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

struct deleter
{
    void operator()(int *p)
    {
        delete p;
    }
};

int main()
{
    std::shared_ptr<int> sp0;
    std::cout << "(bool)sp0 == " << std::boolalpha
        << (bool)sp0 << std::endl;

    std::shared_ptr<int> sp1(new int(5));
    std::cout << "*sp1 == " << *sp1 << std::endl;

    std::shared_ptr<int> sp2(new int(10), deleter());
    std::cout << "*sp2 == " << *sp2 << std::endl;

    std::shared_ptr<int> sp3(sp2);
    std::cout << "*sp3 == " << *sp3 << std::endl;

    std::weak_ptr<int> wp(sp3);
    std::shared_ptr<int> sp4(wp);
    std::cout << "*sp4 == " << *sp4 << std::endl;

    std::auto_ptr<int> ap(new int(15));
    std::shared_ptr<int> sp5(ap);
    std::cout << "*sp5 == " << *sp5 << std::endl;

    return (0);
}

(bool)sp0 == false
*sp1 == 5
*sp2 == 10
*sp3 == 10
*sp4 == 10
*sp5 == 15

`~shared_ptr`

Détruit un shared_ptr.

~shared_ptr();

Notes

Le destructeur décrémente le nombre de références pour la ressource actuellement détenue par *this. Si le nombre de références atteint zéro, la ressource est libérée.

Exemple

// std__memory__shared_ptr_destroy.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp1(new int(5));
    std::cout << "*sp1 == " << *sp1 << std::endl;
    std::cout << "use count == " << sp1.use_count() << std::endl;

    {
        std::shared_ptr<int> sp2(sp1);
        std::cout << "*sp2 == " << *sp2 << std::endl;
        std::cout << "use count == " << sp1.use_count() << std::endl;
    }

    // check use count after sp2 is destroyed
    std::cout << "use count == " << sp1.use_count() << std::endl;

    return (0);
}

*sp1 == 5
use count == 1
*sp2 == 5
use count == 2
use count == 1

`swap`

Échange deux objets shared_ptr.

void swap(shared_ptr& sp) noexcept;

Paramètres

sp
Pointeur partagé à échanger.

Notes

La fonction membre laisse la ressource détenue à l’origine par *this devenir la propriété de sp, et la ressource détenue à l’origine par sp devenir la propriété de *this. La fonction ne modifie pas le nombre de références pour les deux ressources et ne lève aucune exception.

Exemple

// std__memory__shared_ptr_swap.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp1(new int(5));
    std::shared_ptr<int> sp2(new int(10));
    std::cout << "*sp1 == " << *sp1 << std::endl;

    sp1.swap(sp2);
    std::cout << "*sp1 == " << *sp1 << std::endl;

    swap(sp1, sp2);
    std::cout << "*sp1 == " << *sp1 << std::endl;
    std::cout << std::endl;

    std::weak_ptr<int> wp1(sp1);
    std::weak_ptr<int> wp2(sp2);
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;

    wp1.swap(wp2);
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;

    swap(wp1, wp2);
    std::cout << "*wp1 == " << *wp1.lock() << std::endl;

    return (0);
}

*sp1 == 5
*sp1 == 10
*sp1 == 5
*wp1 == 5
*wp1 == 10
*wp1 == 5

`unique`

Teste si la ressource détenue est unique. Cette fonction a été déconseillée en C++17 et supprimée en C++20.

bool unique() const noexcept;

Notes

La fonction membre retourne true si aucun autre objet shared_ptr détient la ressource qui appartient à *this. Sinon, elle retourne false.

Exemple

// std__memory__shared_ptr_unique.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp1(new int(5));
    std::cout << "sp1.unique() == " << std::boolalpha
        << sp1.unique() << std::endl;

    std::shared_ptr<int> sp2(sp1);
    std::cout << "sp1.unique() == " << std::boolalpha
        << sp1.unique() << std::endl;

    return (0);
}

sp1.unique() == true
sp1.unique() == false

`use_count`

Compte le nombre de propriétaires de ressources.

long use_count() const noexcept;

Notes

La fonction membre retourne le nombre d’objets shared_ptr qui détiennent la ressource appartenant à *this.

Exemple

// std__memory__shared_ptr_use_count.cpp
// compile with: /EHsc
#include <memory>
#include <iostream>

int main()
{
    std::shared_ptr<int> sp1(new int(5));
    std::cout << "sp1.use_count() == "
        << sp1.use_count() << std::endl;

    std::shared_ptr<int> sp2(sp1);
    std::cout << "sp1.use_count() == "
        << sp1.use_count() << std::endl;

    return (0);
}

sp1.use_count() == 1
sp1.use_count() == 2

`weak_type`

Type d’un pointeur faible vers un élément.

using weak_type = weak_ptr<T>; // C++17

Notes

La weak_type définition a été ajoutée en C++17.

Voir aussi

Informations de référence sur les fichiers d’en-tête
<memory>
unique_ptr
weak_ptr, classe

Classe shared_ptr

Syntaxe

Notes

Cohérence de thread

Membres

element_type

Notes

Exemple

get

Notes

Exemple

operator bool

Notes

Exemple

operator*

Notes

Exemple

operator=

Paramètres

Notes

Exemple

operator->

Notes

Exemple

owner_before

Paramètres

Notes

reset

Paramètres

Notes

Exemple

shared_ptr

Paramètres

Notes

Exemple

~shared_ptr

Notes

Exemple

swap

Paramètres

Notes

Exemple

unique

Notes

Exemple

use_count

Notes

Exemple

weak_type

Notes

Voir aussi

Commentaires

Commentaires

Ressources supplémentaires

Classe `shared_ptr`

`element_type`

`get`

`operator bool`

`operator*`

`operator=`

`operator->`

`owner_before`

`reset`

`shared_ptr`

`~shared_ptr`

`swap`

`unique`

`use_count`

`weak_type`