# Intro 
This is yet another implementation of an intrusive [reference counting](http://en.wikipedia.org/wiki/Reference_counting) 
[smart pointer](http://en.wikipedia.org/wiki/Smart_pointer), a highly configurable reference-counted base class and adapters.

The code requires a C++17 or above compiler.

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

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

Documentation and formal tests are a work in progress.

<!-- TOC depthfrom:2 -->

- [Why bother?](#why-bother)
    - [Named conversions from raw pointers](#named-conversions-from-raw-pointers)
    - [No ADL](#no-adl)
    - [Support for output parameters](#support-for-output-parameters)
    - [Support for operator->*](#support-for-operator-)
    - [Atomic access](#atomic-access)
    - [Trivial ABI](#trivial-abi)
    - [Correct implementation of a "reference-counted base" class](#correct-implementation-of-a-reference-counted-base-class)
    - [Support for weak pointers](#support-for-weak-pointers)
- [Integration](#integration)
    - [CMake via FetchContent](#cmake-via-fetchcontent)
    - [Conan](#conan)
    - [Vcpkg](#vcpkg)
    - [Meson via subproject](#meson-via-subproject)
    - [Platform package managers](#platform-package-managers)
    - [Building and installing on your system](#building-and-installing-on-your-system)
        - [Using CMake](#using-cmake)
        - [Using Meson](#using-meson)
    - [Using installed package](#using-installed-package)
        - [Basic use](#basic-use)
        - [CMake package](#cmake-package)
        - [Meson package](#meson-package)
        - [Via pkg-config](#via-pkg-config)
    - [Copying to your sources](#copying-to-your-sources)
- [Usage](#usage)
    - [Basics](#basics)
    - [Using provided base classes](#using-provided-base-classes)
    - [Supporting weak pointers](#supporting-weak-pointers)
    - [Using with Apple CoreFoundation types](#using-with-apple-corefoundation-types)
    - [Using with Microsoft COM interfaces](#using-with-microsoft-com-interfaces)
    - [Using with Python objects](#using-with-python-objects)
    - [Using with non-reference-counted types](#using-with-non-reference-counted-types)
    - [Atomic operations](#atomic-operations)
- [Constexpr functionality](#constexpr-functionality)
- [Module support](#module-support)
- [Reference](#reference)

<!-- /TOC -->

## Why bother?
There are multiple other intrusive smart pointers available, including one from [Boost](https://www.boost.org/doc/libs/1_71_0/libs/smart_ptr/doc/html/smart_ptr.html#intrusive_ptr),
and there was even a [proposal](http://open-std.org/JTC1/SC22/WG21/docs/papers/2016/p0468r0.html) 
to 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 time
of 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:

### Named conversions from raw pointers
All other libraries offer a conversion in the form 
`smart_ptr(T * p);`
In my opinion, this is an extremely bad idea. When looking at a call like `smart_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 depends 
on the smart pointer implementation or even on specific traits used. This makes the behavior invisible and hard to predict at the **call site**. It guarantees that someone, somewhere will make a wrong assumption. In my experience, almost all reference-counting bugs happen on the **boundary** between code that uses smart and raw pointers where such conversions are abundant. 
Just like any form of dangerous cast, this one has to be **explicit** in calling code. As an aside, Objective-C ARC did it right
with 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 the constructor isn't a solution.
Can you quickly tell what `smart_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.

### No ADL 

Many libraries use [ADL](https://en.wikipedia.org/wiki/Argument-dependent_name_lookup) to find "add reference" and 
"release reference" functions for the underlying type.
That is, they have expressions like `add_ref(p)` in their implementation, and expect a function named `add_ref` that accepts a pointer to the underlying type to be found via ADL.
This solution is great in many cases but it breaks when working with some C types like Apple's `CFTypeRef`. This one is actually a typedef to `void *`, so if you have an `add_ref` that accepts it, you have just made every unrelated `void *` 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.

### Support for output parameters

Oftentimes you need to pass a smart pointer as an output parameter to a C function that takes `T **`.
Many other smart pointers either 
- ignore this scenario, requiring you to introduce an extra raw pointer and unsafe code, or
- overload `operator&`, which is a horrendously bad idea (it breaks lots of generic code which assumes that `&foo` gives
  an address of foo, not something else).
The right solution is to have a proxy class convertible to `T **`.

Since C++23, the standard library provides `std::out_ptr` and `std::inout_ptr` to deal with this issue. This library
fully supports those when they are available.

When standard library support is not available, this library also exposes `get_output_param()` and `get_inout_param()` 
methods that return an inner proxy class (which behaves similarly to `std::out_ptr_t`/`std::inout_ptr`).

### Support for `operator->*`

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

### Atomic access

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 of `std::atomic<intrusive_shared_ptr<...>>` extending the normal `std::atomic` semantics to it.

### Trivial ABI

When built with the Clang compiler, `intrusive_shared_ptr` is marked with the [\[\[clang::trivial_abi\]\]](https://clang.llvm.org/docs/AttributeReference.html#trivial-abi) 
attribute. A good description of what this attribute does and why it is important
for performance can be found [here](https://quuxplusone.github.io/blog/2018/05/02/trivial-abi-101/).
Another take on the performance issue as a comment on the standard library proposal can be found 
[here](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1351r0.html#params).
[This page](doc/trivial_abi.md) contains details on why this is a good idea and why concerns about the order of destruction do not really matter here.

### Correct implementation of a "reference-counted base" class

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

### Support for weak pointers

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


## Integration

### CMake via FetchContent

```cmake
include(FetchContent)
...

FetchContent_Declare(isptr
    GIT_REPOSITORY  https://github.com/gershnik/intrusive_shared_ptr.git
    GIT_TAG         v1.13  #use the tag, branch or SHA you need
    GIT_SHALLOW     TRUE
)
...
FetchContent_MakeAvailable(isptr)
...

#To use header files:
target_link_libraries(mytarget
PRIVATE
  isptr::isptr
)

#To use C++ module (the second param is the visibility)
isptr_add_module(mytarget PRIVATE)
```
> ℹ&#xFE0F; _[What is FetchContent?](https://cmake.org/cmake/help/latest/module/FetchContent.html)_

### Conan

Add `intrusive_shared_ptr/1.13` to your conanfile.

### Vcpkg

In classic mode, run the following vcpkg command:
```bash
vcpkg install intrusive-shared-ptr
```

In manifest mode, run the following vcpkg command in your project directory:
```bash
vcpkg add port intrusive-shared-ptr
```

### Meson via subproject

Place an `isptr.wrap` file in your `subprojects` directory:

```ini
[wrap-git]
url = https://github.com/gershnik/intrusive_shared_ptr.git
revision = v1.13
depth = 1

[provide]
dependency_names = isptr, isptr-module
```

Set `revision` to the tag, branch or SHA you need.

Then, in your `meson.build`:

```meson
#To use header files add the dependency to your target:
isptr_dep = dependency('isptr')
executable('mytarget', 'main.cpp', dependencies : isptr_dep)

#To use the C++ module add this dependency instead:
isptr_module_dep = dependency('isptr-module')
executable('mytarget', 'main.cpp', dependencies : isptr_module_dep)
```

The `isptr-module` dependency adds `isptr.cppm` to whatever target consumes it so you can
`import isptr;` from that target. The module is compiled privately into the target.

### Platform package managers

On Debian-based systems `intrusive-shared-ptr` might be available via APT.

> [!TIP]
> The version available from APT is usually pretty old and, thus, by definition buggy. It is recommended to  
> rely on other methods if at all possible.

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

If available, it can be installed via

```bash
apt install libisptr-dev
```

### Building and installing on your system

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

#### Using CMake

1. Download or clone this repository into SOME_PATH
2. On the command line:
```bash
cd SOME_PATH
cmake -S . -B build 

#If you wish to run tests 
#cmake --build build 
#ctest --test-dir build --output-on-failure

#install to /usr/local
sudo cmake --install build
#or for a different prefix
#cmake --install build --prefix /usr
```

#### Using Meson

1. Download or clone this repository into SOME_PATH
2. On the command line:
```bash
cd SOME_PATH

#install to /usr/local
meson setup build
sudo meson install -C build

#or for a different prefix
#meson setup build --prefix /usr
#sudo meson install -C build
```

### Using installed package

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

#### Basic use 

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

To use the C++ module, include `<prefix>/share/isptr/isptr.cppm` in your build.


#### CMake package

```cmake
find_package(isptr)

#To use header files:
target_link_libraries(mytarget
PRIVATE
  isptr::isptr
)

#To use the C++ module (the second param is the visibility)
isptr_add_module(mytarget PRIVATE)
```

#### Meson package

```meson
#To use header files add the dependency to your target:
isptr_dep = dependency('isptr')
executable('mytarget', 'main.cpp', dependencies : isptr_dep)

#To use the C++ module add isptr.cppm to your target instead:
isptr_module = dependency('isptr').get_variable(pkgconfig : 'module')
executable('mytarget', 'main.cpp', isptr_module)
```

#### Via `pkg-config`

To use header files, add the output of `pkg-config --cflags isptr` to your compiler flags.

To use the module, add the output of `pkg-config --variable=module isptr` (it will be the path to a .cppm file) to your build.

Note that the default installation prefix `/usr/local` might not be in the list of places your
`pkg-config` looks into. If so, you might need to do:
```bash
export PKG_CONFIG_PATH=/usr/local/share/pkgconfig
```
before running `pkg-config`.


### Copying to your sources

You can also simply download this repository from the [Releases](https://github.com/gershnik/intrusive_shared_ptr/releases) page 
(named `intrusive_shared_ptr-X.Y.tar.gz`) and unpack it somewhere in your source tree.

To use header files, add the `inc` sub-directory to your include path.

To use the module, add `modules/isptr.cppm` to your build. 

## Usage

### Basics

All the types in this library are declared in `namespace isptr`. For brevity, the namespace is omitted below.
Add the `isptr::` prefix to all the types or use a `using` declaration in your own code.

The header `<intrusive_shared_ptr/intrusive_shared_ptr.h>`/module `isptr` provides a template

```cpp
template<class T, class Traits>
class intrusive_shared_ptr<T, Traits>;
```

Where `T` is the type of the pointee and `Traits` is a class that should provide 2 static functions that look like this:

```cpp
static void add_ref(SomeType * ptr) noexcept
{  
    //increment reference count. ptr is guaranteed to be non-nullptr
}
static void sub_ref(SomeType * ptr) noexcept
{ 
    //decrement reference count. ptr is guaranteed to be non-nullptr
}
```

`SomeType *` should be a pointer type to which `T *` is convertible. It is possible to make `add_ref` and `sub_ref`
templates, if desired, though this is usually not necessary.


To create `intrusive_shared_ptr` from a raw `T *`, there are 2 functions:

```cpp
//pass the smart pointer in without changing the reference count
template<class T, class Traits>
intrusive_shared_ptr<T, Traits> intrusive_shared_ptr<T, Traits>::noref(T * p) noexcept;

//adopt the pointer and bump the reference count
template<class T, class Traits>
intrusive_shared_ptr<T, Traits> intrusive_shared_ptr<T, Traits>::ref(T * p) noexcept;
```

It is possible to use `intrusive_shared_ptr` directly, but the name is long and ugly, so a better approach is to
wrap it in a typedef and provide wrapper functions like this:

```cpp
struct my_type
{};

struct my_intrusive_traits
{
    static void add_ref(my_type * ptr) noexcept; //implement
    static void sub_ref(my_type * ptr) noexcept; //implement
};

template<class T>
using my_ptr = intrusive_shared_ptr<T, my_intrusive_traits>;

template<class T> 
my_ptr<T> my_retain_func(T * ptr) {
    return my_ptr<T>::ref(ptr);
}
template<class T> 
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 of `my_type`, then
it is possible to simplify things even further with the header `refcnt_ptr.h`. It adapts `intrusive_shared_ptr` to traits
exposed as an inner type `refcnt_ptr_traits`. You can use it like this:

```cpp
#include <intrusive_shared_ptr/refcnt_ptr.h>
//Or, if using modules:
//import isptr;

using namespace isptr;

struct my_type
{
  struct refcnt_ptr_traits
  {
      static void add_ref(my_type * ptr) noexcept; //implement
      static void sub_ref(my_type * ptr) noexcept; //implement
  };
};

//now you can use refcnt_ptr<my_type> for the pointer type and the refcnt_attach and refcnt_retain free functions

//create from raw pointer (created with count 1)
my_type * raw = new my_type();
refcnt_ptr<my_type> p1 = refcnt_attach(raw);

//create directly
auto p1 = make_refcnt<my_type>();

//assign from raw pointer bumping reference count
refcnt_ptr<my_type> p2;
p2 = refcnt_retain(raw);


```


### Using provided base classes

To implement `my_type` above, the library provides a base class you can inherit from which will do the right thing.

```cpp
#include <intrusive_shared_ptr/ref_counted.h>
#include <intrusive_shared_ptr/refcnt_ptr.h>
//Or, if using modules:
//import isptr;

using namespace isptr;

class foo : ref_counted<foo>
{
    friend ref_counted;
public:    
    void method();
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 directly
refcnt_ptr<foo> p2 = make_refcnt<foo>();

//assign from raw pointer bumping reference count
foo * raw = ...
refcnt_ptr<foo> p3 = refcnt_retain(raw);

```

The type of the reference count is `int` by default. If you need to, you can customize it. 

```cpp

class tiny : 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 on [this page](https://gershnik.github.io/intrusive_shared_ptr/ref_counted.html)

### Supporting weak pointers

If you want to support weak pointers, you need to tell `ref_counted` about it. Since weak pointers include overhead
even if you never create one, by default they are disabled.

```cpp
#include <intrusive_shared_ptr/ref_counted.h>
#include <intrusive_shared_ptr/refcnt_ptr.h>
//Or, if using modules:
//import isptr;

using namespace isptr;

class foo : weak_ref_counted<foo> //alias for ref_counted<foo, ref_counted_flags::provide_weak_references>
{
    void method();
};

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 be `intptr_t`.
More details can be found on [this page](https://gershnik.github.io/intrusive_shared_ptr/ref_counted.html)

### Using with Apple CoreFoundation types

```cpp

#include <intrusive_shared_ptr/apple_cf_ptr.h>
//Or, if using modules:
//import isptr;

using namespace isptr;

//Use auto in real code. The type is spelled out for clarity
cf_ptr<CFStringRef> 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);

```

### Using with Microsoft COM interfaces

```cpp

#include <intrusive_shared_ptr/com_ptr.h>
//Or, if using modules:
//import isptr;

using namespace isptr;

com_shared_ptr<IStream> pStream;
//Before C++23
CreateStreamOnHGlobal(nullptr, true, pStream.get_output_param());
//With C++23 and later
CreateStreamOnHGlobal(nullptr, true, std::out_ptr(pStream));
pStream->Write(....);

```

### Using with Python objects

```cpp
#include <intrusive_shared_ptr/python_ptr.h>
//Or, if using modules:
//import isptr;

using namespace isptr;

auto str = py_attach(PyUnicode_FromString("Hello"));
std::cout << PyUnicode_GetLength(str.get());

```

### Using with non-reference-counted types

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

Adapter:
```cpp
#include <intrusive_shared_ptr/ref_counted.h>
//Or, if using modules:
//import isptr;

using counted_map = ref_counted_adapter<std::map<std::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<std::string, int>>;

auto ptr1 = make_refcnt<weakly_counted_map>();
(*ptr1)["abc"] = 7;
std::cout << ptr1->size();
weakly_counted_map::weak_ptr w1 = ptr1->get_weak_ptr();
refcnt_ptr<weakly_counted_map> p2 = w1->lock();
```

Wrapper:
```cpp
#include <intrusive_shared_ptr/ref_counted.h>
//Or, if using modules:
//import isptr;

using counted_map = ref_counted_wrapper<std::map<std::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<std::string, int>>;

auto ptr1 = make_refcnt<weakly_counted_map>();
ptr1->wrapped["abc"] = 7;
std::cout << ptr1->wrapped.size();
weakly_counted_map::weak_ptr w1 = ptr1->get_weak_ptr();
refcnt_ptr<weakly_counted_map> p2 = w1->lock();
```

### Atomic operations

The library provides a partial specialization 

```cpp

template <class T, class Traits>
std::atomic<intrusive_shared_ptr<T, Traits>>;

```

which exposes normal `std::atomic` functionality. For example:

```cpp

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();
//or
ptr = aptr;

aptr.store(ptr);
//or
aptr = ptr;

my_ptr ptr1 = aptr.exchange(ptr);

//etc.

```

## Constexpr functionality

When built with a C++20 compiler, `intrusive_shared_ptr` is fully constexpr capable. You can do things like

```cpp

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.

## Module support

Since version 1.5, this library supports being used as a C++ module. 
This mode is currently **experimental**. Please report bugs if you encounter any issues.

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

If using CMake, follow the requirements at [cmake-cxxmodules](https://cmake.org/cmake/help/latest/manual/cmake-cxxmodules.7.html). 

The library consists of a single module file at [modules/isptr.cppm](modules/isptr.cppm). 
This file is auto-generated from all the library headers. Include it in your build.

If using CMake, the `isptr_add_module` function is provided to simplify doing so (see [Integration](#integration) section above).

If using Meson, depend on `isptr-module` to add the module to a target, or use the pkg-config `module` variable 
to locate it when consuming an installed package (see [Integration](#integration) section above).

## Reference

The reference documentation for this library can be found at https://gershnik.github.io/intrusive_shared_ptr





