From 80dfa1cc772c8bb8cf11f6ad2caf2bbedd877be0 Mon Sep 17 00:00:00 2001
From: Nick Hastings <nshastings@gmail.com>
Date: Sat, 19 Oct 2024 13:20:20 -0400
Subject: [PATCH] Add Clone to Handle methodmap

---
 core/logic/smn_handles.cpp  |  1 +
 plugins/include/handles.inc | 27 +++++++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/core/logic/smn_handles.cpp b/core/logic/smn_handles.cpp
index 9add7fd4f2..0ebb4d4fba 100644
--- a/core/logic/smn_handles.cpp
+++ b/core/logic/smn_handles.cpp
@@ -119,6 +119,7 @@ REGISTER_NATIVES(handles)
 	{"CloseHandle",				sm_CloseHandle},
 	{"CloneHandle",				sm_CloneHandle},
 	{"GetMyHandle",				sm_GetMyHandle},
+	{"Handle.Clone",			sm_CloneHandle},
 	{"Handle.Close",			sm_CloseHandle},
 	{"Handle.~Handle",			sm_CloseHandle},
 	{NULL,						NULL},
diff --git a/plugins/include/handles.inc b/plugins/include/handles.inc
index 759f5af399..2c152ee9b1 100644
--- a/plugins/include/handles.inc
+++ b/plugins/include/handles.inc
@@ -78,7 +78,34 @@ native Handle CloneHandle(Handle hndl, Handle plugin=INVALID_HANDLE);
 methodmap Handle __nullable__ {
     public native ~Handle();
 
+    /**
+     * Closes a Handle.  If the handle has multiple copies open,
+     * it is not destroyed unless all copies are closed.
+     *
+     * @note Closing a Handle has a different meaning for each Handle type.  Make
+     *       sure you read the documentation on whatever provided the Handle.
+     *
+     * @error           Invalid handles will cause a run time error.
+     */
     public native void Close();
+
+    /**
+     * Clones a Handle.  When passing handles in between plugins, caching handles
+     * can result in accidental invalidation when one plugin releases the Handle, or is its owner
+     * is unloaded from memory.  To prevent this, the Handle may be "cloned" with a new owner.
+     *
+     * @note Usually, you will be cloning Handles for other plugins.  This means that if you clone
+     *       the Handle without specifying the new owner, it will assume the identity of your original
+     *       calling plugin, which is not very useful.  You should either specify that the receiving
+     *       plugin should clone the handle on its own, or you should explicitly clone the Handle
+     *       using the receiving plugin's identity Handle.
+     *
+     * @param plugin    Optional Handle to another plugin to mark as the new owner.
+     *                  If no owner is passed, the owner becomes the calling plugin.
+     * @return          Handle on success, INVALID_HANDLE if not cloneable.
+     * @error           Invalid handles will cause a run time error.
+     */
+    public native Handle Clone(Handle plugin=INVALID_HANDLE);
 };
 
 /**