jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[perl] Document explicitly not to use %OWNER directly

Browse source 
See #1771
This commit is contained in:
Olly Betts 2022-01-18 14:51:55 +13:00
commit c839066405
1 changed files with 11 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

15
Doc/Manual/Perl5.html
View file

@ -2651,8 +2651,8 @@ constructors and destructors for the package and are always named
"new" and "DESTROY". The constructor always returns a tied hash "new" and "DESTROY". The constructor always returns a tied hash
table. This hash table is used to access the member variables of a table. This hash table is used to access the member variables of a
structure in addition to being able to invoke member functions. The structure in addition to being able to invoke member functions. The
<tt>%OWNER</tt> and <tt>%BLESSEDMEMBERS</tt> hash tables are used <tt>%OWNER</tt> and <tt>%BLESSEDMEMBERS</tt> hash tables are
internally and described shortly. implementation details used internally and described shortly.
</p> </p>
<p> <p>
@ -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 corresponding Perl object (this situation turns out to come up
frequently when constructing objects like linked lists and trees). frequently when constructing objects like linked lists and trees).
When C takes possession of an object, you can change Perl's ownership When C takes possession of an object, you can change Perl's ownership
by simply deleting the object from the <tt>%OWNER</tt> hash. This is by calling the <tt>DISOWN</tt> method (which will delete the object
done using the <tt>DISOWN</tt> method. from the internal <tt>%OWNER</tt> hash).
</p>
<p>
The <tt>%OWNER</tt> hash is an implementation detail, discussed here
only to help clarify the operation of <tt>ACQUIRE</tt> and <tt>DISOWN</tt>.
You should not access <tt>%OWNER</tt> directly - the details of how it
works (and possibly even its existence) may chance in future SWIG versions.
</p> </p>
<div class="targetlang"><pre> <div class="targetlang"><pre>