Diff coverage report for

//

//

// Copyright (c) 2022 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2022 Vinnie Falco (vinnie.falco@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/boostorg/url

// Official repository: https://github.com/boostorg/url

//

//

#ifndef BOOST_URL_GRAMMAR_RECYCLED_HPP

#ifndef BOOST_URL_GRAMMAR_RECYCLED_HPP

#define BOOST_URL_GRAMMAR_RECYCLED_HPP

#define BOOST_URL_GRAMMAR_RECYCLED_HPP

#include <boost/url/detail/config.hpp>

#include <boost/url/detail/config.hpp>

#include <boost/url/grammar/detail/recycled.hpp>

#include <boost/url/grammar/detail/recycled.hpp>

#include <atomic>

#include <atomic>

#include <cstddef>

#include <cstddef>

#include <type_traits>

#include <type_traits>

#include <stddef.h> // ::max_align_t

#include <stddef.h> // ::max_align_t

#if !defined(BOOST_URL_DISABLE_THREADS)

#if !defined(BOOST_URL_DISABLE_THREADS)

# include <mutex>

# include <mutex>

#endif

#endif

namespace boost {

namespace boost {

namespace urls {

namespace urls {

namespace grammar {

namespace grammar {

/** Provides an aligned storage buffer aligned for T

/** Provides an aligned storage buffer aligned for T

    @code

    @code

    template<class T>

    template<class T>

    struct aligned_storage

    struct aligned_storage

    {

    {

        /// Return a pointer to the aligned storage area

        /// Return a pointer to the aligned storage area

        void* addr() noexcept;

        void* addr() noexcept;

        /// Return a pointer to the aligned storage area

        /// Return a pointer to the aligned storage area

        void const* addr() const noexcept;

        void const* addr() const noexcept;

    };

    };

    @endcode

    @endcode

 */

 */

template<class T>

template<class T>

using aligned_storage =

using aligned_storage =

    implementation_defined::aligned_storage_impl<

    implementation_defined::aligned_storage_impl<

        implementation_defined::nearest_pow2(sizeof(T), 64),

        implementation_defined::nearest_pow2(sizeof(T), 64),

            (alignof(::max_align_t) > alignof(T)) ?

            (alignof(::max_align_t) > alignof(T)) ?

                alignof(::max_align_t) : alignof(T)>;

                alignof(::max_align_t) : alignof(T)>;

//------------------------------------------------

//------------------------------------------------

/** A thread-safe collection of instances of T

/** A thread-safe collection of instances of T

    Instances of this type may be used to control

    Instances of this type may be used to control

    where recycled instances of T come from when

    where recycled instances of T come from when

    used with @ref recycled_ptr.

    used with @ref recycled_ptr.

    @par Example

    @par Example

    @code

    @code

    static recycled< std::string > bin;

    static recycled< std::string > bin;

    recycled_ptr< std::string > ps( bin );

    recycled_ptr< std::string > ps( bin );

    // Put the string into a known state

    // Put the string into a known state

    ps->clear();

    ps->clear();

    @endcode

    @endcode

    @see

    @see

        @ref recycled_ptr.

        @ref recycled_ptr.

*/

*/

template<class T>

template<class T>

class recycled

class recycled

{

{

public:

public:

    /** Destructor

    /** Destructor

        All recycled instances of T are destroyed.

        All recycled instances of T are destroyed.

        Undefined behavior results if there are

        Undefined behavior results if there are

        any @ref recycled_ptr which reference

        any @ref recycled_ptr which reference

        this recycle bin.

        this recycle bin.

    */

    */

    ~recycled();

    ~recycled();

    /** Constructor

    /** Constructor

    */

    */

    constexpr recycled() = default;

    constexpr recycled() = default;

private:

private:

    template<class>

    template<class>

    friend class recycled_ptr;

    friend class recycled_ptr;

    struct U

    struct U

    {

    {

        T t;

        T t;

        U* next = nullptr;

        U* next = nullptr;

#if !defined(BOOST_URL_DISABLE_THREADS)

#if !defined(BOOST_URL_DISABLE_THREADS)

        std::atomic<

        std::atomic<

            std::size_t> refs;

            std::size_t> refs;

#else

#else

        std::size_t refs;

        std::size_t refs;

#endif

#endif

        {

        {

    };

    };

    struct report;

    struct report;

    U* acquire();

    U* acquire();

    void release(U* u) noexcept;

    void release(U* u) noexcept;

    U* head_ = nullptr;

    U* head_ = nullptr;

#if !defined(BOOST_URL_DISABLE_THREADS)

#if !defined(BOOST_URL_DISABLE_THREADS)

    std::mutex m_;

    std::mutex m_;

#endif

#endif

};

};

//------------------------------------------------

//------------------------------------------------

/** A pointer to a shared instance of T

/** A pointer to a shared instance of T

    This is a smart pointer container which can

    This is a smart pointer container which can

    acquire shared ownership of an instance of

    acquire shared ownership of an instance of

    `T` upon or after construction. The instance

    `T` upon or after construction. The instance

    is guaranteed to be in a valid, but unknown

    is guaranteed to be in a valid, but unknown

    state. Every recycled pointer references

    state. Every recycled pointer references

    a valid recycle bin.

    a valid recycle bin.

    @par Example

    @par Example

    @code

    @code

    static recycled< std::string > bin;

    static recycled< std::string > bin;

    recycled_ptr< std::string > ps( bin );

    recycled_ptr< std::string > ps( bin );

    // Put the string into a known state

    // Put the string into a known state

    ps->clear();

    ps->clear();

    @endcode

    @endcode

    @tparam T the type of object to

    @tparam T the type of object to

        acquire, which must be

        acquire, which must be

        <em>DefaultConstructible</em>.

        <em>DefaultConstructible</em>.

*/

*/

template<class T>

template<class T>

class recycled_ptr

class recycled_ptr

{

{

    // T must be default constructible!

    // T must be default constructible!

    static_assert(

    static_assert(

        std::is_default_constructible<T>::value,

        std::is_default_constructible<T>::value,

        "T must be DefaultConstructible");

        "T must be DefaultConstructible");

    friend class recycled<T>;

    friend class recycled<T>;

    using B = recycled<T>;

    using B = recycled<T>;

    using U = typename B::U;

    using U = typename B::U;

    B* bin_ = nullptr;

    B* bin_ = nullptr;

    U* p_ = nullptr;

    U* p_ = nullptr;

public:

public:

    /** Destructor

    /** Destructor

        If this is not empty, shared ownership

        If this is not empty, shared ownership

        of the pointee is released. If this was

        of the pointee is released. If this was

        the last reference, the object is

        the last reference, the object is

        returned to the original recycle bin.

        returned to the original recycle bin.

        @par Effects

        @par Effects

        @code

        @code

        this->release();

        this->release();

        @endcode

        @endcode

    */

    */

    ~recycled_ptr();

    ~recycled_ptr();

    /** Constructor

    /** Constructor

        Upon construction, this acquires

        Upon construction, this acquires

        exclusive access to an object of type

        exclusive access to an object of type

        `T` which is either recycled from the

        `T` which is either recycled from the

        specified bin, or newly allocated.

        specified bin, or newly allocated.

        The object is in an unknown but

        The object is in an unknown but

        valid state.

        valid state.

        @par Example

        @par Example

        @code

        @code

        static recycled< std::string > bin;

        static recycled< std::string > bin;

        recycled_ptr< std::string > ps( bin );

        recycled_ptr< std::string > ps( bin );

        // Put the string into a known state

        // Put the string into a known state

        ps->clear();

        ps->clear();

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->bin() == &bin && ! this->empty()

        &this->bin() == &bin && ! this->empty()

        @endcode

        @endcode

        @param bin The recycle bin to use

        @param bin The recycle bin to use

        @see

        @see

            @ref recycled.

            @ref recycled.

    */

    */

    explicit

    explicit

    recycled_ptr(recycled<T>& bin);

    recycled_ptr(recycled<T>& bin);

    /** Constructor

    /** Constructor

        After construction, this is empty and

        After construction, this is empty and

        refers to the specified recycle bin.

        refers to the specified recycle bin.

        @par Example

        @par Example

        @code

        @code

        static recycled< std::string > bin;

        static recycled< std::string > bin;

        recycled_ptr< std::string > ps( bin, nullptr );

        recycled_ptr< std::string > ps( bin, nullptr );

        // Acquire a string and put it into a known state

        // Acquire a string and put it into a known state

        ps->acquire();

        ps->acquire();

        ps->clear();

        ps->clear();

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->bin() == &bin && this->empty()

        &this->bin() == &bin && this->empty()

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param bin The recycle bin to use

        @param bin The recycle bin to use

        @see

        @see

            @ref acquire,

            @ref acquire,

            @ref recycled,

            @ref recycled,

            @ref release.

            @ref release.

    */

    */

    recycled_ptr(

    recycled_ptr(

        recycled<T>& bin,

        recycled<T>& bin,

        std::nullptr_t) noexcept;

        std::nullptr_t) noexcept;

    /** Constructor

    /** Constructor

        Upon construction, this acquires

        Upon construction, this acquires

        exclusive access to an object of type

        exclusive access to an object of type

        `T` which is either recycled from a

        `T` which is either recycled from a

        global recycle bin, or newly allocated.

        global recycle bin, or newly allocated.

        The object is in an unknown but

        The object is in an unknown but

        valid state.

        valid state.

        @par Example

        @par Example

        @code

        @code

        recycled_ptr< std::string > ps;

        recycled_ptr< std::string > ps;

        // Put the string into a known state

        // Put the string into a known state

        ps->clear();

        ps->clear();

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->bin() != nullptr && ! this->empty()

        &this->bin() != nullptr && ! this->empty()

        @endcode

        @endcode

        @see

        @see

            @ref recycled.

            @ref recycled.

    */

    */

    recycled_ptr();

    recycled_ptr();

    /** Constructor

    /** Constructor

        After construction, this is empty

        After construction, this is empty

        and refers to a global recycle bin.

        and refers to a global recycle bin.

        @par Example

        @par Example

        @code

        @code

        recycled_ptr< std::string > ps( nullptr );

        recycled_ptr< std::string > ps( nullptr );

        // Acquire a string and put it into a known state

        // Acquire a string and put it into a known state

        ps->acquire();

        ps->acquire();

        ps->clear();

        ps->clear();

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->bin() != nullptr && this->empty()

        &this->bin() != nullptr && this->empty()

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @see

        @see

            @ref acquire,

            @ref acquire,

            @ref recycled,

            @ref recycled,

            @ref release.

            @ref release.

    */

    */

    recycled_ptr(

    recycled_ptr(

        std::nullptr_t) noexcept;

        std::nullptr_t) noexcept;

    /** Constructor

    /** Constructor

        If `other` references an object, the

        If `other` references an object, the

        newly constructed pointer acquires

        newly constructed pointer acquires

        shared ownership. Otherwise this is

        shared ownership. Otherwise this is

        empty. The new pointer references

        empty. The new pointer references

        the same recycle bin as `other`.

        the same recycle bin as `other`.

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->bin() == &other->bin() && this->get() == other.get()

        &this->bin() == &other->bin() && this->get() == other.get()

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The pointer to copy

        @param other The pointer to copy

    */

    */

    recycled_ptr(

    recycled_ptr(

        recycled_ptr const& other) noexcept;

        recycled_ptr const& other) noexcept;

    /** Constructor

    /** Constructor

        If `other` references an object,

        If `other` references an object,

        ownership is transferred including

        ownership is transferred including

        a reference to the recycle bin. After

        a reference to the recycle bin. After

        the move, the moved-from object is empty.

        the move, the moved-from object is empty.

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->bin() == &other->bin() && ! this->empty() && other.empty()

        &this->bin() == &other->bin() && ! this->empty() && other.empty()

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The pointer to move from

        @param other The pointer to move from

    */

    */

    recycled_ptr(

    recycled_ptr(

        recycled_ptr&& other) noexcept;

        recycled_ptr&& other) noexcept;

    /** Assignment

    /** Assignment

        If `other` references an object,

        If `other` references an object,

        ownership is transferred including

        ownership is transferred including

        a reference to the recycle bin. After

        a reference to the recycle bin. After

        the move, the moved-from object is empty.

        the move, the moved-from object is empty.

        @par Effects

        @par Effects

        @code

        @code

        this->release()

        this->release()

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->bin() == &other->bin()

        &this->bin() == &other->bin()

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The pointer to move from

        @param other The pointer to move from

        @return `*this`

        @return `*this`

    */

    */

    recycled_ptr&

    recycled_ptr&

    operator=(

    operator=(

        recycled_ptr&& other) noexcept;

        recycled_ptr&& other) noexcept;

    /** Assignment

    /** Assignment

        If `other` references an object,

        If `other` references an object,

        this acquires shared ownership and

        this acquires shared ownership and

        references the same recycle bin as

        references the same recycle bin as

        `other`. The previous object if any

        `other`. The previous object if any

        is released.

        is released.

        @par Effects

        @par Effects

        @code

        @code

        this->release()

        this->release()

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->bin() == &other->bin() && this->get() == other.get()

        &this->bin() == &other->bin() && this->get() == other.get()

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The pointer to copy from

        @param other The pointer to copy from

        @return `*this`

        @return `*this`

    */

    */

    recycled_ptr&

    recycled_ptr&

    operator=(

    operator=(

        recycled_ptr const& other) noexcept;

        recycled_ptr const& other) noexcept;

    /** Return true if this does not reference an object

    /** Return true if this does not reference an object

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return `p_ == nullptr`

        @return `p_ == nullptr`

    */

    */

    bool

    bool

    empty() const noexcept

    empty() const noexcept

    {

    {

        return p_ == nullptr;

        return p_ == nullptr;

    }

    }

    /** Return true if this references an object

    /** Return true if this references an object

        @par Effects

        @par Effects

        @code

        @code

        return ! this->empty();

        return ! this->empty();

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return `!this->empty()`

        @return `!this->empty()`

    */

    */

    explicit

    explicit

    {

    {

    }

    }

    /** Return the referenced recycle bin

    /** Return the referenced recycle bin

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return A reference to the recycle bin

        @return A reference to the recycle bin

    */

    */

    recycled<T>&

    recycled<T>&

    bin() const noexcept

    bin() const noexcept

    {

    {

        return *bin_;

        return *bin_;

    }

    }

    /** Return the referenced object

    /** Return the referenced object

        If this is empty, `nullptr` is returned.

        If this is empty, `nullptr` is returned.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return A pointer to the object

        @return A pointer to the object

    */

    */

    {

    {

    }

    }

    /** Return the referenced object

    /** Return the referenced object

        If this is empty, `nullptr` is returned.

        If this is empty, `nullptr` is returned.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return A pointer to the object

        @return A pointer to the object

    */

    */

    {

    {

    }

    }

    /** Return the referenced object

    /** Return the referenced object

        @par Preconditions

        @par Preconditions

        @code

        @code

        not this->empty()

        not this->empty()

        @endcode

        @endcode

        @return A reference to the object

        @return A reference to the object

    */

    */

    T& operator*() const noexcept

    T& operator*() const noexcept

    {

    {

        return *get();

        return *get();

    }

    }

    /** Return the referenced object

    /** Return the referenced object

        If this references an object, it is

        If this references an object, it is

        returned. Otherwise, exclusive ownership

        returned. Otherwise, exclusive ownership

        of a new object of type `T` is acquired

        of a new object of type `T` is acquired

        and returned.

        and returned.

        @par Postconditions

        @par Postconditions

        @code

        @code

        not this->empty()

        not this->empty()

        @endcode

        @endcode

        @return A reference to the object

        @return A reference to the object

    */

    */

    T& acquire();

    T& acquire();

    /** Release the referenced object

    /** Release the referenced object

        If this references an object, it is

        If this references an object, it is

        released to the referenced recycle bin.

        released to the referenced recycle bin.

        The pointer continues to reference

        The pointer continues to reference

        the same recycle bin.

        the same recycle bin.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->empty()

        this->empty()

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

    */

    */

    void release() noexcept;

    void release() noexcept;

};

};

} // grammar

} // grammar

} // urls

} // urls

} // boost

} // boost

#include <boost/url/grammar/impl/recycled.hpp>

#include <boost/url/grammar/impl/recycled.hpp>

#endif

#endif