From 9f0a565c3d99b7f10fbcd2cf71d4f2f821551f28 Mon Sep 17 00:00:00 2001 From: Etienne Kneuss Date: Wed, 31 Aug 2011 19:47:32 +0000 Subject: [PATCH] Draft for weakref documentation git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@315918 c90b9560-bf6c-de11-be94-00142212c4b1 --- appendices/extensions.xml | 2 + reference/weakref/book.xml | 92 +++++++++++++ reference/weakref/setup.xml | 53 ++++++++ reference/weakref/weakref.xml | 120 +++++++++++++++++ reference/weakref/weakref/acquire.xml | 164 ++++++++++++++++++++++++ reference/weakref/weakref/construct.xml | 113 ++++++++++++++++ reference/weakref/weakref/get.xml | 62 +++++++++ reference/weakref/weakref/release.xml | 108 ++++++++++++++++ reference/weakref/weakref/test.php | 33 +++++ reference/weakref/weakref/valid.xml | 63 +++++++++ 10 files changed, 810 insertions(+) create mode 100644 reference/weakref/book.xml create mode 100644 reference/weakref/setup.xml create mode 100644 reference/weakref/weakref.xml create mode 100644 reference/weakref/weakref/acquire.xml create mode 100644 reference/weakref/weakref/construct.xml create mode 100644 reference/weakref/weakref/get.xml create mode 100644 reference/weakref/weakref/release.xml create mode 100644 reference/weakref/weakref/test.php create mode 100644 reference/weakref/weakref/valid.xml diff --git a/appendices/extensions.xml b/appendices/extensions.xml index d43c4fe669..dfec4eab56 100644 --- a/appendices/extensions.xml +++ b/appendices/extensions.xml @@ -213,6 +213,7 @@ + @@ -561,6 +562,7 @@ + diff --git a/reference/weakref/book.xml b/reference/weakref/book.xml new file mode 100644 index 0000000000..85efda8c3c --- /dev/null +++ b/reference/weakref/book.xml @@ -0,0 +1,92 @@ + + + + + + Weak References + Weakref + + + &reftitle.intro; + + Weak references provide a non-intrusive gateway to ephemere objects. Unlike + normal (strong) references, weak references do not prevent the garbage + collector from freeing that object. For this reason, an object may be + destroyed even though a weak reference to that object still exists. In such + conditions, the weak reference seamlessly becomes invalid. + + + + + <classname>Weakref</classname> usage example + +valid()) { + echo "Object still exists!\n"; + var_dump($r1->get()); +} else { + echo "Object is dead!\n"; +} + +unset($o1); + +if ($r1->valid()) { + echo "Object still exists!\n"; + var_dump($r1->get()); +} else { + echo "Object is dead!\n"; +} +?> +]]> + + &example.outputs; + + + + + + + + &reference.weakref.setup; + &reference.weakref.weakref; + + + + + diff --git a/reference/weakref/setup.xml b/reference/weakref/setup.xml new file mode 100644 index 0000000000..db67cc5285 --- /dev/null +++ b/reference/weakref/setup.xml @@ -0,0 +1,53 @@ + + + + + &reftitle.setup; + +
+ &reftitle.required; + &no.requirement; +
+ +
+ &reftitle.install; + + &pecl.moved; + + + &pecl.info; + &url.pecl.package;weakref. + + + &pecl.windows.download; + +
+ +
+ &reftitle.resources; + &no.resource; +
+ +
+ + + diff --git a/reference/weakref/weakref.xml b/reference/weakref/weakref.xml new file mode 100644 index 0000000000..b7dcb437fe --- /dev/null +++ b/reference/weakref/weakref.xml @@ -0,0 +1,120 @@ + + + + The Weakref class + Weakref + + + + +
+ &reftitle.intro; + + The Weakref class provides a gateway to objects without preventing the garbage collector from freeing those objects. + It also provides a way to turn a weak reference into a strong one. + +
+ + +
+ &reftitle.classsynopsis; + + + + Weakref + + + + + + Weakref + + + + + + &Methods; + + + + +
+ +
+ &reftitle.examples; + + + <classname>Weakref</classname> usage example + +valid()) { + echo "Object still exists!\n"; + var_dump($r1->get()); +} else { + echo "Object is dead!\n"; +} + +unset($o1); + +if ($r1->valid()) { + echo "Object still exists!\n"; + var_dump($r1->get()); +} else { + echo "Object is dead!\n"; +} +?> +]]> + + &example.outputs; + + + + + +
+ + +
+ + &reference.weakref.entities.weakref; + +
+ + + diff --git a/reference/weakref/weakref/acquire.xml b/reference/weakref/weakref/acquire.xml new file mode 100644 index 0000000000..de2b92172f --- /dev/null +++ b/reference/weakref/weakref/acquire.xml @@ -0,0 +1,164 @@ + + + + + Weakref::acquire + Aquires a strong reference on that object + + + + &reftitle.description; + + public boolWeakref::acquire + + + + Acquires a strong reference on that object, virtually turning the weak + reference into a strong one. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns &true; if the reference was valid and could be turned into a strong + reference, &false; otherwise. + + + + + &reftitle.examples; + + + <function>Weakref::acquire</function> example + +acquire(); + +echo "Unsetting o1...\n"; +unset($o1); + +$o2 = $r1->get(); + +$r1->release(); + +echo "Unsetting o2...\n"; +unset($o2); +?> +]]> + + &example.outputs; + + + + + + + + + Nested acquire/release example + +acquire(); + +echo " Unsetting...\n"; +unset($o1); + +echo " Acquiring...\n"; +$r1->acquire(); + +echo " Acquiring...\n"; +$r1->acquire(); + +echo " Releasing...\n"; +$r1->release(); + +echo " Releasing...\n"; +$r1->release(); + +echo "Releasing...\n"; +$r1->release(); + +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + Weakref::release + + + + + + + diff --git a/reference/weakref/weakref/construct.xml b/reference/weakref/weakref/construct.xml new file mode 100644 index 0000000000..0ca91c08d4 --- /dev/null +++ b/reference/weakref/weakref/construct.xml @@ -0,0 +1,113 @@ + + + + + Weakref::__construct + Constructs a new weak reference + + + + &reftitle.description; + + public Weakref::__construct + objectobject + + + Constructs a new weak reference. + + + + + &reftitle.parameters; + + + + object + + + The object to reference. + + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.examples; + + + <function>Weakref::__construct</function> example + +valid()) { + echo "Object still exists!\n"; + var_dump($r1->get()); +} else { + echo "Object is dead!\n"; +} + +unset($o1); + +if ($r1->valid()) { + echo "Object still exists!\n"; + var_dump($r1->get()); +} else { + echo "Object is dead!\n"; +} +?> +]]> + + &example.outputs; + + + + + + + + + diff --git a/reference/weakref/weakref/get.xml b/reference/weakref/weakref/get.xml new file mode 100644 index 0000000000..c8e37672cb --- /dev/null +++ b/reference/weakref/weakref/get.xml @@ -0,0 +1,62 @@ + + + + + Weakref::get + Returns the object pointed to by the weak reference + + + + &reftitle.description; + + public objectWeakref::get + + + + Returns the object pointed to by the weak reference. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the object if the reference is still valid, &null; otherwise. + + + + + &reftitle.seealso; + + + Weakref::valid + + + + + + + diff --git a/reference/weakref/weakref/release.xml b/reference/weakref/weakref/release.xml new file mode 100644 index 0000000000..9c496b956a --- /dev/null +++ b/reference/weakref/weakref/release.xml @@ -0,0 +1,108 @@ + + + + + Weakref::release + Releases a previously acquired reference + + + + &reftitle.description; + + public boolWeakref::release + + + + Releases a previously acquired reference. Potentially turning a strong + reference back into a weak reference. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns &true; if the reference was previously acquired and thus could be + released, &false; otherwise. + + + + + &reftitle.examples; + + + <function>Weakref::release</function> example + +acquire(); + +echo "Unsetting o1...\n"; +unset($o1); + +$o2 = $r1->get(); + +$r1->release(); + +echo "Unsetting o2...\n"; +unset($o2); +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + Weakref::acquire + + + + + + + diff --git a/reference/weakref/weakref/test.php b/reference/weakref/weakref/test.php new file mode 100644 index 0000000000..70f3fbea74 --- /dev/null +++ b/reference/weakref/weakref/test.php @@ -0,0 +1,33 @@ +acquire(); + +echo " Unsetting...\n"; +unset($o1); + +echo " Acquiring...\n"; +$r1->acquire(); + +echo " Acquiring...\n"; +$r1->acquire(); + +echo " Releasing...\n"; +$r1->release(); + +echo " Releasing...\n"; +$r1->release(); + +echo "Releasing...\n"; +$r1->release(); + +?> diff --git a/reference/weakref/weakref/valid.xml b/reference/weakref/weakref/valid.xml new file mode 100644 index 0000000000..8166de0263 --- /dev/null +++ b/reference/weakref/weakref/valid.xml @@ -0,0 +1,63 @@ + + + + + Weakref::valid + Checks whether the object referenced still exists + + + + &reftitle.description; + + public boolWeakref::valid + + + + Checks whether the object referenced still exists. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns &true; if the object still exists and is thus still accessible via + Weakref::get, &false; otherwise. + + + + + &reftitle.seealso; + + + Weakref::get + + + + + + +