Repository files navigation

This is yet another implementation of an intrusivereference countingsmart pointer, highly configurable reference counted base class and adapters.

The code requires C++17 or above compiler.

It is known to work with:
Xcode 11 or above
Microsoft Visual Studio 2019 or above
Clang 8 or above
GCC 7.4.0 or above

It can be used either as a classical header-only library or as C++ module (experimental).

Documentation and formal tests are work in progress.

• Why bother?
  • Named conversions from raw pointers
  • No ADL
  • Support for output parameters
  • Support for operator->*
  • Atomic access
  • Trivial ABI
  • Correct implementation of a "reference counted base" class
  • Support for weak pointers
• Integration
  • CMake via FetchContent
  • Conan
  • Vcpkg
  • Platform package managers
  • Building and installing on your system
    • Basic use
    • CMake package
    • Via pkg-config
  • Copying to your sources
• Usage
  • Basics
  • Using provided base classes
  • Supporting weak pointers
  • Using with Apple CoreFoundation types
  • Using with Microsoft COM interfaces
  • Using with Python objects
  • Using with non-reference counted types
  • Atomic operations
• Constexpr functionality
• Module support
• Reference

There are multiple other intrusive smart pointers available including one fromBoostand there was even aproposalto add one to the standard C++ library, so why create another one?Unfortunately, as far as I can tell, all existing implementations, and that includes the standard library proposal at the timeof this writing, suffer from numerous deficiencies that make them hard or annoying to use in real life code.The most serious problems addressed here are as follows

All other libraries offer a conversion in the formsmart_ptr(T * p);In my opinion, this is an extremely bad idea. When looking at a call likesmart_ptr(foo()) can you quickly tell whether this adds a reference count or "attaches" the smart pointer to a raw one? That's right, you cannot! The answer dependson the smart pointer implementation or even on specific traits used. This makes the behavior invisible and hard to predict at thecall site. It guarantees that someone, somewhere will make a wrong assumption. In my experience, almost all reference counting bugs happen on theboundary between code that uses smart and raw pointers where such conversions are abundant.Just like any form of dangerous cast this one has to beexplicit in calling code. As an aside, ObjectiveC ARC did it rightwith their explicit and visible__bridge casts between raw and smart pointers.Note that having a boolean argument (like what Boost and many other implementations do) in constructor isn't a solution.Can you quickly tell whatsmart_ptr(p, true) does? Is it "true, add reference" or "true, copy it"?

This library uses named functions to perform conversion. You see exactly what is being done at the call site.

Many libraries useADL to find "add reference" and"release reference" functions for the underlying type.That is, they have expressions likeadd_ref(p) in their implementation, and expect a function namedadd_ref that accepts pointer to the underlying type is supposed to be found via ADL.This solution is great in many cases but it breaks when working with some C types like Apple'sCTypeRef. This one is actually a typedef tovoid * so if you have anadd_ref that accepts it, you have just made every unrelatedvoid * reference counted (with very bad results if you accidentally put a wrong object into a smart pointer).A better way to define how reference counting is done is to pass a traits class to the smart pointer. (The standard library proposal gets this one right).

This library uses traits.

Often times you need to pass smart pointer as an output parameter to a C function that takesT **Many other smart pointers either

• ignore this scenario, requiring you to introduce extra raw pointer and unsafe code, or
• overloadoperator& which is a horrendously bad idea (it breaks lots of generic code which assumes that&foo givesan address of foo, not something else)The right solution is to have a proxy class convertible toT **.

Since C++23 the standard library providesstd::out_ptr andstd::inout_ptr to deal with this issue. This libraryfully supports those when they are available.

When standard library support is not available, this library also exposesget_output_param() andget_inout_parammethods that return an inner proxy class (which behaves similarly tostd::out_ptr_t/std::inout_ptr)

This might seem to be a minor thing but is really annoying in generic code. For some reason no smart pointers bother to provideoperator->* so that pointers to members could be accessed via the same syntax as for raw pointers. In non-generic codeyou can always work around it via(*p).*whatever but in generic code this is not an option.

Sometimes you need to operate on smart pointers atomically. To the best of my knowledge no library currently provides this functionality.

This library provides a specialization ofstd::atomic<intrusive_shared_ptr<...>> extending to it the normalstd::atomic semantics.

When built with CLang compilerintrusive_shared_ptr is marked with[[clang::trivial_abi]]attribute. A good description of what this attribute does and why it is importantfor performance can be foundhere.Another take on the performance issue as a comment on standard library proposal can be foundhere.This page contains details on why this is a good idea and why concerns about order of destruction do not really matter here.

This is not directly a problem with smart pointers but with the base classes often provided together with them to implement anintrusively counted class. Very often they contain subtle bugs (see'A note on implementing reference counted objects' for more details). It is also tricky tocreate a base class that can work well for different requirements without compromising efficiency.

Continuing on the base class theme, when doing intrusive reference counting, supporting (or not) weak pointers is the responsibilityof the counted class. Supporting weak pointers also usually involves tradeoffs in terms of performance or memory consumption.This library base class allows user to enable a decent implementation of weak pointers via policy based design.

include(FetchContent)...FetchContent_Declare(isptr    GIT_REPOSITORY  https://github.com/gershnik/intrusive_shared_ptr.git    GIT_TAG         v1.9#use the tag, branch or sha you need    GIT_SHALLOWTRUE)...FetchContent_MakeAvailable(isptr)...#To use header files:target_link_libraries(mytargetPRIVATE  isptr::isptr)#To use C++ module (the second param is the visibilty)isptr_add_module(mytargetPRIVATE)

ℹ️What is FetchContent?

Addintrusive_shared_ptr/1.9 to your conanfile.

In classic mode, run the following vcpkg command:

vcpkg install intrusive-shared-ptr

In manifest mode, run the following vcpkg command in your project directory:

vcpkg add port intrusive-shared-ptr

On Debian based systemsintrusive-shared-ptr might be available via APT.

You can consulthttps://pkgs.org/search/?q=libisptr-dev for up-to-date availability information.

If available, it can be installed via

apt install libisptr-dev

You can also build and install this library on your system using CMake.

1. Download or clone this repository into SOME_PATH
2. On command line:

cd SOME_PATHcmake -S. -B build#Optional#cmake --build build --target run-test#install to /usr/localsudo cmake --install build#or for a different prefix#cmake --install build --prefix /usr

Once the library has been installed it can be used in the following ways:

To use the header files set the include directory to<prefix>/include where<prefix>is the install prefix from above.

To use C++ module (if enabled during the build) include<prefix>/include/intrusive_shared_ptr/isptr.cppmin your build.

find_package(isptr)#To use header files:target_link_libraries(mytargetPRIVATE  isptr::isptr)#To use C++ module (the second param is the visibilty)isptr_add_module(mytargetPRIVATE)

Add the output ofpkg-config --cflags isptr to your compiler flags.

Note that the default installation prefix/usr/local might not be in the list of places yourpkg-config looks into. If so you might need to do:

export PKG_CONFIG_PATH=/usr/local/share/pkgconfig

before runningpkg-config

You can also simply download this repository fromReleases page(namedintrusive_shared_ptr-X.Y.tar.gz) and unpack it somewhere in your source tree.

To use header files add theinc sub-directory to your include path.

To use the module addmodules/isptr.cppm to your build.

All the types in this library are declared innamespace isptr. For brevity the namespace is omitted below.Addisptr:: prefix to all the type or useusing declaration in your own code.

The header<intrusive_shared_ptr/intrusive_shared_ptr.h>/moduleisptr provides a template

template<classT,classTraits>classintrusive_shared_ptr<T, Traits>;

WhereT is the type of the pointee andTraits a class that should provide 2 static functions that look like this

staticvoidadd_ref(SomeType * ptr)noexcept{//increment reference count. ptr is guaranteed to be non-nullptr}staticvoidsub_ref(SomeType * ptr)noexcept{//decrement reference count. ptr is guaranteed to be non-nullptr}

SomeType * should be a pointer type to whichT * is convertible to. It is possible to makeadd_ref andsub_reftemplates, if desired, though this is usually not necessary.

To createintrusive_shared_ptr from a rawT * there are 2 functions:

//pass the smart pointer in without changing the reference counttemplate<classT,classTraits>intrusive_shared_ptr<T, Traits> intrusive_shared_ptr<T, Traits>::noref(T * p)noexcept;//adopt the pointer and bump the reference counttemplate<classT,classTraits>intrusive_shared_ptr<T, Traits> intrusive_shared_ptr<T, Traits>::ref(T * p)noexcept

It is possible to useintrusive_shared_ptr directly but the name is long and ugly so a better approach is towrap in a typedef and wrapper functions like this

structmy_type{};structmy_intrusive_traits{staticvoidadd_ref(my_type * ptr)noexcept;//implementstaticvoidsub_ref(my_type * ptr)noexcept;//implement};template<classT>using my_ptr = intrusive_shared_ptr<T, my_intrusive_traits>;template<classT> my_ptr<T>my_retain_func(T * ptr) {return my_ptr<T>::ref(ptr);}template<classT> my_ptr<T>my_attach_func(T * ptr) {return my_ptr<T>::noref(ptr);}

The library provides such wrappers for some common scenarios. If you fully control the definition ofmy_type thenit is possible to simplify things even further with headerrefcnt_ptr.h. It adaptsintrusive_shared_ptr to traitsexposed as inner typerefcnt_ptr_traits. You can use it like this:

#include<intrusive_shared_ptr/refcnt_ptr.h>//Or, if using modules://import isptr;usingnamespaceisptr;structmy_type{structrefcnt_ptr_traits  {staticvoidadd_ref(my_type * ptr)noexcept;//implementstaticvoidsub_ref(my_type * ptr)noexcept;//implement  };};//now you can use refcnt_ptr<my_type> for the pointer type and refcnt_attach and refcnt_retain free functions e.g.//create from raw pointer (created with count 1)foo raw =new my_type();refcnt_ptr<my_type> p1 = refcnt_attach(raw);//create directlyauto p1 = make_refcnt<my_type>();//assign from raw pointer bumping reference countrefcnt_ptr<my_type> p2;p2 = refcnt_retain(raw);

To implementmy_type above the library provides a base class you can inherit from which will do the right thing.

#include<intrusive_shared_ptr/ref_counted.h>#include<intrusive_shared_ptr/refcnt_ptr.h>//Or, if using modules://import isptr;usingnamespaceisptr;classfoo : ref_counted<foo>{friend ref_counted;public:voidmethod();private:~foo()noexcept =default;//prevent manual deletion};//you can use auto to declare p1, p2 and p3. The full type is spelled out for//demonstration purposes only//attach from raw pointer (created with count 1)refcnt_ptr<foo> p1 = refcnt_attach(new foo());//create directlyrefcnt_ptr<foo> p2 = make_refcnt<foo>();//assign from raw pointer bumping reference countfoo * raw = ...refcnt_ptr<foo> p3 = refcnt_retain(raw);

The type of the reference count isint by default. If you need to you can customize it.

classtiny : ref_counted<tiny, ref_counted_flags::none,char>//use char as count type{friend ref_counted;char c;};static_assert(sizeof(tiny) ==2);

More details can be found inthis document

If you want to support weak pointers you need to tellref_counted about it. Since weak pointers include overheadeven if you never create one, by default they are disabled.

#include<intrusive_shared_ptr/ref_counted.h>#include<intrusive_shared_ptr/refcnt_ptr.h>//Or, if using modules://import isptr;usingnamespaceisptr;classfoo : weak_ref_counted<foo>//alias for ref_counted<foo, ref_counted_flags::provide_weak_references>{voidmethod();};refcnt_ptr<foo> p1 = refcnt_attach(new foo());foo::weak_ptr w1 = p1->get_weak_ptr();refcnt_ptr<foo> p2 = w1->lock();

Note that you cannot customize the type of reference count if you support weak pointers - it will always beintptr_t.More details can be found inthis document

#include<intrusive_shared_ptr/apple_cf_ptr.h>//Or, if using modules://import isptr;usingnamespaceisptr;//Use auto in real code. Type is spelled out for claritycf_ptr<CStringRef> str = cf_attach(CFStringCreateWithCString(nullptr,"Hello",kCFStringEncodingUTF8));std::cout << CFStringGetLength(str.get());CFArrayRef raw = ...;//Use auto in real code.cf_ptr<CFArrayRef> array = cf_retain(raw);

#include<intrusive_shared_ptr/com_ptr.h>//Or, if using modules://import isptr;usingnamespaceisptr;com_shared_ptr<IStream> pStream;//Before C++23CreateStreamOnHGlobal(nullptr,true, pStream.get_output_param());//With C++23 and laterCreateStreamOnHGlobal(nullptr,true, std::out_ptr(pStream));pStream->Write(....);

#include<intrusive_shared_ptr/python_ptr.h>//Or, if using modules://import isptr;usingnamespaceisptr;auto str = py_attach(PyUnicode_FromString("Hello"));std::cout << PyUnicode_GetLength(str.get());

On occasion when you have a code that uses intrusive reference counting a lot you might need to handle a typewhich you cannot modify and which is not by itself reference counted.In such situation you can use an adapter (if you prefer derivation) or wrapper (if you prefer containment) that makes it such

Adapter:

#include<intrusive_shared_ptr/ref_counted.h>//Or, if using modules://import isptr;using counted_map = ref_counted_adapter<std::map<string,int>>;auto ptr = make_refcnt<counted_map>();(*ptr)["abc"] =7;std::cout << ptr->size();using weakly_counted_map = weak_ref_counted_adapter<std::map<string,int>>;auto ptr1 = make_refcnt<weakly_counted_map>();(*ptr1)["abc"] =7;std::cout << ptr1->size();foo::weak_ptr w1 = p1->get_weak_ptr();refcnt_ptr<weakly_counted_map> p2 = w1->lock();

Wrapper:

#include<intrusive_shared_ptr/ref_counted.h>//Or, if using modules://import isptr;using counted_map = ref_counted_wrapper<std::map<string,int>>;auto ptr = make_refcnt<counted_map>();ptr->wrapped()["abc"] = 7;std::cout << ptr->wrapped().size();using weakly_counted_map = weak_ref_counted_wrapper<std::map<string,int>>;auto ptr1 = make_refcnt<weakly_counted_map>();ptr1->wrapped()["abc"] = 7;std::cout << ptr1->wrapped().size();foo::weak_ptr w1 = p1->get_weak_ptr();refcnt_ptr<weakly_counted_map> p2 = w1->lock();

The library provides a partial specialization

template<classT,classTraits>std::atomic<intrusive_shared_ptr<T, Traits>>;

which exposes normalstd::atomic functionality. For example:

using my_ptr = intrusive_shared_ptr<my_type, my_intrusive_traits>;using my_atomic_ptr = std::atomic<my_ptr>;my_ptr ptr = ...;my_atomic_ptr aptr = ptr;ptr = aptr.load();//orptr = aptr;aptr.store(ptr);//oraptr = ptr;my_ptr ptr1 = aptr.exchange(ptr);//etc.

When built with C++20 compilerintrusive_shared_ptr is fully constexpr capable. You can do things like

using my_ptr = intrusive_shared_ptr<my_type, my_intrusive_traits>;constexpr my_ptr foo;

Due to non-default destructors this functionality is not available on C++17

Since version 1.5 this library support being used as a C++ module.This mode is currentlyexperimental. Please report bugs if you encounter any issues.

In order to use C++ modules you need a compiler that supports them.Currently CLang >= 16 and MSVC toolset >= 14.34 are definitely known to work.Other compilers/versions may or may not work.

If using CMake follow the requirements atcmake-cxxmodules.

The library consists of a single module file atmodules/isptr.cppm.This file is auto-generated from all the library headers. Include it in your build.

• intrusive_shared_ptr.h
• refcnt_ptr.h
• ref_counted.h