NetServices: add the BExclusiveBorrow<T> smart pointer

This smart pointer is designed to help with putting some explicitness and
safety around the case where someone will use their own object that implements
the BDataIO interface to store the body of a network request. By default,
BDataIO objects do not require or enforce thread safety. Since accessing these
unsynchronized objects between two threads is undefined behavior, it should be
explicitly discouraged.

The BExclusiveBorrow/BBorrow smart pointer helper helps solve that by enforcing
the limitations on using an unsynchronized object in two threads. When used
correctly, there is a runtime check on incorrect use by the developer. This
should help write better code.

The design is based on shared_ptr, including having an admin block akin the
control block, that manages the internal object. This type-erased admin block
has the advantage that it allows the owner to have a different type than the
borrower. It also handles cases where the lifetime of the borrower is longer
than the owner: the borrower can continue to use the object until they want to
return it, after which it will be cleaned up. This will make it possible to do
some fire and forget pattern in the network services kit, where someone may
just wants to create a file and borrow it to the network request, and care
about further processing the file in the future.

Change-Id: Ie9b7e7472c868b60f663b4db4fa449d421e447eb

headers/private/netservices2/ExclusiveBorrow.h

@@ -0,0 +1,345 @@
+/*
+ * Copyright 2022 Haiku Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ */
+
+#ifndef _B_EXCLUSIVE_BORROW_H
+#define _B_EXCLUSIVE_BORROW_H
+
+#include <atomic>
+#include <memory>
+
+#include <ErrorsExt.h>
+
+namespace BPrivate {
+
+namespace Network {
+
+
+class BBorrowError : public BError {
+public:
+	BBorrowError(const char* origin)
+		: BError(origin)
+	{
+		
+	}
+
+	virtual const char*
+	Message() const noexcept override
+	{
+		return "BBorrowError";
+	}
+};
+
+
+class BorrowAdmin {
+private:
+	static constexpr uint8 kOwned = 0x1;
+	static constexpr uint8 kBorrowed = 0x2;
+	std::atomic<uint8>	fState = kOwned;
+
+protected:
+	virtual	~BorrowAdmin() = default;
+
+	virtual	void	Cleanup() noexcept {};
+	virtual void	ReleasePointer() noexcept {};
+public:
+	BorrowAdmin() noexcept
+	{
+
+	}
+
+
+	void
+	Borrow()
+	{
+		auto alreadyBorrowed = (fState.fetch_or(kBorrowed) & kBorrowed) == kBorrowed;
+		if (alreadyBorrowed) {
+			throw BBorrowError(__PRETTY_FUNCTION__);
+		}
+	}
+
+
+	void
+	Return() noexcept
+	{
+		auto cleanup = (fState.fetch_and(~kBorrowed) & kOwned) != kOwned;
+		if (cleanup)
+			this->Cleanup();
+	}
+
+
+	void
+	Forfeit() noexcept
+	{
+		auto cleanup = (fState.fetch_and(~kOwned) & kBorrowed) != kBorrowed;
+		if (cleanup)
+			this->Cleanup();
+	}
+
+
+	bool
+	IsBorrowed() noexcept
+	{
+		return (fState.load() & kBorrowed) == kBorrowed;
+	}
+
+
+	void
+	Release()
+	{
+		if ((fState.load() & kBorrowed) == kBorrowed)
+			throw BBorrowError(__PRETTY_FUNCTION__);
+		this->ReleasePointer();
+		this->Cleanup();
+	}
+};
+
+
+template <typename T>
+class BorrowPointer : public BorrowAdmin
+{
+public:
+	BorrowPointer(T* object) noexcept
+		: fPtr(object)
+	{
+
+	}
+
+	virtual ~BorrowPointer() {
+		delete fPtr;
+	}
+
+protected:
+	virtual void
+	Cleanup() noexcept override
+	{
+		delete this;
+	}
+
+	virtual void
+	ReleasePointer() noexcept override
+	{
+		fPtr = nullptr;
+	}
+
+private:
+	T*	fPtr;
+};
+
+
+template <typename T>
+class BExclusiveBorrow {
+	template<typename P>
+	friend class BBorrow;
+
+	T*				fPtr = nullptr;
+	BorrowAdmin*	fAdminBlock = nullptr;
+
+public:
+	BExclusiveBorrow() noexcept
+	{
+
+	}
+
+
+	BExclusiveBorrow(nullptr_t) noexcept
+	{
+
+	}
+
+
+	BExclusiveBorrow(T* object)
+	{
+		fAdminBlock = new BorrowPointer<T>(object);
+		fPtr = object;
+	}
+
+	~BExclusiveBorrow()
+	{
+		if (fAdminBlock)
+			fAdminBlock->Forfeit();
+	}
+
+	BExclusiveBorrow(const BExclusiveBorrow&) = delete;
+
+
+	BExclusiveBorrow& operator=(const BExclusiveBorrow&) = delete;
+
+
+	BExclusiveBorrow(BExclusiveBorrow&& other) noexcept
+	{
+		if (fAdminBlock)
+			fAdminBlock->Forfeit();
+		fAdminBlock = other.fAdminBlock;
+		fPtr = other.fPtr;
+		other.fAdminBlock = nullptr;
+		other.fPtr = nullptr;
+	}
+
+
+	BExclusiveBorrow&
+	operator=(BExclusiveBorrow&& other) noexcept
+	{
+		if (fAdminBlock)
+			fAdminBlock->Forfeit();
+		fAdminBlock = other.fAdminBlock;
+		fPtr = other.fPtr;
+		other.fAdminBlock = nullptr;
+		other.fPtr = nullptr;
+		return *this;
+	}
+
+
+	bool
+	HasValue() const noexcept
+	{
+		return bool(fPtr);
+	}
+
+
+	T&
+	operator*() const
+	{
+		if (fAdminBlock && !fAdminBlock->IsBorrowed())
+			return *fPtr;
+		throw BBorrowError(__PRETTY_FUNCTION__);
+	}
+
+
+	T*
+	operator->() const
+	{
+		if (fAdminBlock && !fAdminBlock->IsBorrowed())
+			return fPtr;
+		throw BBorrowError(__PRETTY_FUNCTION__);
+	}
+
+
+	std::unique_ptr<T>
+	Release()
+	{
+		if (!fAdminBlock)
+			throw BBorrowError(__PRETTY_FUNCTION__);
+		fAdminBlock->Release();
+		auto retval = std::unique_ptr<T>(fPtr);
+		fPtr = nullptr;
+		fAdminBlock = nullptr;
+		return retval;
+	}
+};
+
+
+template <typename T>
+class BBorrow {
+	T*				fPtr = nullptr;
+	BorrowAdmin*	fAdminBlock = nullptr;
+
+public:
+	BBorrow() noexcept
+	{
+
+	}
+
+
+	BBorrow(nullptr_t) noexcept
+	{
+
+	}
+
+
+	template<typename P>
+	explicit BBorrow(BExclusiveBorrow<P>& owner)
+		: fPtr(owner.fPtr), fAdminBlock(owner.fAdminBlock)
+	{
+		fAdminBlock->Borrow();
+	}
+
+
+	BBorrow(const BBorrow&) = delete;
+
+
+	BBorrow& operator=(const BBorrow&) = delete;
+
+
+	BBorrow(BBorrow&& other) noexcept
+		: fPtr(other.fPtr), fAdminBlock(other.fAdminBlock)
+	{
+		other.fPtr = nullptr;
+		other.fAdminBlock = nullptr;
+	}
+
+
+	BBorrow&
+	operator=(BBorrow&& other) noexcept
+	{
+		if (fAdminBlock)
+			fAdminBlock->Return();
+
+		fPtr = other.fPtr;
+		fAdminBlock = other.fAdminBlock;
+		other.fPtr = nullptr;
+		other.fAdminBlock = nullptr;
+		return *this;
+	}
+
+
+	~BBorrow()
+	{
+		if (fAdminBlock)
+			fAdminBlock->Return();
+	}
+
+
+	bool
+	HasValue() const noexcept
+	{
+		return bool(fPtr);
+	}
+
+
+	T&
+	operator*() const
+	{
+		if (fPtr)
+			return *fPtr;
+		throw BBorrowError(__PRETTY_FUNCTION__);
+	}
+
+
+	T*
+	operator->() const
+	{
+		if (fPtr)
+			return fPtr;
+		throw BBorrowError(__PRETTY_FUNCTION__);
+	}
+
+
+	void
+	Return() noexcept
+	{
+		if (fAdminBlock)
+			fAdminBlock->Return();
+		fAdminBlock = nullptr;
+		fPtr = nullptr;
+	}
+};
+
+
+template<class T, class ..._Args>
+BExclusiveBorrow<T>
+make_exclusive_borrow(_Args&& ...__args)
+{
+	auto guardedObject = std::make_unique<T>(std::forward<_Args>(__args)...);
+	auto retval = BExclusiveBorrow<T>(guardedObject.get());
+	guardedObject.release();
+	return retval;
+}
+
+
+} // namespace Network
+
+} // namespace BPrivate
+
+#endif // _B_EXCLUSIVE_BORROW_H