From c839066405d0700bdd17d7669eff623dab8fd928 Mon Sep 17 00:00:00 2001 From: Olly Betts Date: Tue, 18 Jan 2022 14:51:55 +1300 Subject: [PATCH] [perl] Document explicitly not to use %OWNER directly See #1771 --- Doc/Manual/Perl5.html | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index 85c2545cf..9f2e08ba4 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -2651,8 +2651,8 @@ constructors and destructors for the package and are always named "new" and "DESTROY". The constructor always returns a tied hash table. This hash table is used to access the member variables of a structure in addition to being able to invoke member functions. The -%OWNER and %BLESSEDMEMBERS hash tables are used -internally and described shortly. +%OWNER and %BLESSEDMEMBERS hash tables are +implementation details used internally and described shortly.

@@ -2740,8 +2740,15 @@ to a C function that remembers the object, and then destroy the corresponding Perl object (this situation turns out to come up frequently when constructing objects like linked lists and trees). When C takes possession of an object, you can change Perl's ownership -by simply deleting the object from the %OWNER hash. This is -done using the DISOWN method. +by calling the DISOWN method (which will delete the object +from the internal %OWNER hash). +

+ +

+The %OWNER hash is an implementation detail, discussed here +only to help clarify the operation of ACQUIRE and DISOWN. +You should not access %OWNER directly - the details of how it +works (and possibly even its existence) may chance in future SWIG versions.