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); }; /**