Add ExternalShared and RawRefCount (#23013)

Add `bun.ptr.ExternalShared`, a shared pointer whose reference count is
managed externally; e.g., by extern functions. This can be used to work
with `RefCounted` C++ objects in Zig. For example:

```cpp
// C++:
struct MyType : RefCounted<MyType> { ... };
extern "C" void MyType__ref(MyType* self) { self->ref(); }
extern "C" void MyType__ref(MyType* self) { self->deref(); }
```

```zig
// Zig:
const MyType = opaque {
    extern fn MyType__ref(self: *MyType) void;
    extern fn MyType__deref(self: *MyType) void;

    pub const Ref = bun.ptr.ExternalShared(MyType);

    // This enables `ExternalShared` to work.
    pub const external_shared_descriptor = struct {
        pub const ref = MyType__ref;
        pub const deref = MyType__deref;
    };
};

// Now `MyType.Ref` behaves just like `Ref<MyType>` in C++:
var some_ref: MyType.Ref = someFunctionReturningMyTypeRef();
const ptr: *MyType = some_ref.get(); // gets the inner pointer
var some_other_ref = some_ref.clone(); // increments the ref count
some_ref.deinit(); // decrements the ref count
// decrements the ref count again; if no other refs exist, the object
// is destroyed
some_other_ref.deinit();
```

This commit also adds `RawRefCount`, a simple wrapper around an integer
reference count that can be used to implement the interface required by
`ExternalShared`. Generally, for reference-counted Zig types,
`bun.ptr.Shared` is preferred, but occasionally it is useful to have an
“intrusive” reference-counted type where the ref count is stored in the
type itself. For this purpose, `ExternalShared` + `RawRefCount` is more
flexible and less error-prone than the deprecated `bun.ptr.RefCounted`
type.

(For internal tracking: fixes STAB-1287, STAB-1288)

src/ptr/external_shared.zig

@@ -0,0 +1,111 @@
+/// A shared pointer whose reference count is managed externally; e.g., by extern functions.
+///
+/// `T.external_shared_descriptor` must be a struct of the following form:
+///
+///     pub const external_shared_descriptor = struct {
+///         pub fn ref(T*) void;
+///         pub fn deref(T*) void;
+///     };
+pub fn ExternalShared(comptime T: type) type {
+    _ = T.external_shared_descriptor.ref; // must define a `ref` function
+    _ = T.external_shared_descriptor.deref; // must define a `deref` function
+    return struct {
+        const Self = @This();
+
+        #impl: *T,
+
+        /// `incremented_raw` should have already had its ref count incremented by 1.
+        pub fn adopt(incremented_raw: *T) Self {
+            return .{ .#impl = incremented_raw };
+        }
+
+        /// Deinitializes the shared pointer, decrementing the ref count.
+        pub fn deinit(self: *Self) void {
+            T.external_shared_descriptor.deref(self.#impl);
+            self.* = undefined;
+        }
+
+        /// Gets the underlying pointer. This pointer may not be valid after `self` is
+        /// deinitialized.
+        pub fn get(self: Self) *T {
+            return self.#impl;
+        }
+
+        /// Clones the shared pointer, incrementing the ref count.
+        pub fn clone(self: Self) Self {
+            T.external_shared_descriptor.ref(self.#impl);
+            return self;
+        }
+
+        pub fn cloneFromRaw(raw: *T) Self {
+            T.external_shared_descriptor.ref(raw);
+            return .{ .#impl = raw };
+        }
+
+        /// Returns the raw pointer without decrementing the ref count. Invalidates `self`.
+        pub fn leak(self: *Self) *T {
+            defer self.* = undefined;
+            return self.#impl;
+        }
+
+        const NonOptional = Self;
+
+        pub const Optional = struct {
+            #impl: ?*T = null,
+
+            pub fn initNull() Optional {
+                return .{};
+            }
+
+            /// `incremented_raw`, if non-null, should have already had its ref count incremented
+            /// by 1.
+            pub fn adopt(incremented_raw: ?*T) Optional {
+                return .{ .#impl = incremented_raw };
+            }
+
+            pub fn deinit(self: *Optional) void {
+                if (self.#impl) |impl| {
+                    T.external_shared_descriptor.deref(impl);
+                }
+                self.* = undefined;
+            }
+
+            pub fn get(self: Optional) ?*T {
+                return self.#impl;
+            }
+
+            /// Sets `self` to null.
+            pub fn take(self: *Optional) ?NonOptional {
+                const result: NonOptional = .{ .#impl = self.#impl orelse return null };
+                self.#impl = null;
+                return result;
+            }
+
+            pub fn clone(self: Optional) Optional {
+                if (self.#impl) |impl| {
+                    T.external_shared_descriptor.ref(impl);
+                }
+                return self;
+            }
+
+            pub fn cloneFromRaw(raw: ?*T) Optional {
+                if (raw) |some_raw| {
+                    T.external_shared_descriptor.ref(some_raw);
+                }
+                return .{ .#impl = raw };
+            }
+
+            /// Returns the raw pointer without decrementing the ref count. Invalidates `self`.
+            pub fn leak(self: *Optional) ?*T {
+                defer self.* = undefined;
+                return self.#impl;
+            }
+        };
+
+        /// Invalidates `self`.
+        pub fn intoOptional(self: *Self) Optional {
+            defer self.* = undefined;
+            return .{ .#impl = self.#impl };
+        }
+    };
+}