Add SoftReference and AbstractReference

Author: pinepain

README.md

@@ -4,8 +4,9 @@
 [![Windows Build status](https://ci.appveyor.com/api/projects/status/7r07eydi6c3lj36a/branch/master?svg=true)](https://ci.appveyor.com/project/pinepain/php-weak)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/pinepain/php-weak/master/LICENSE)
 
-This extension provides [weak references](https://en.wikipedia.org/wiki/Weak_reference) support for PHP 7 and serves
-as a ground for other weak data structures.
+This extension adds [Soft Reference](https://en.wikipedia.org/wiki/Weak_reference) and
+[Weak References](https://en.wikipedia.org/wiki/Weak_reference) to PHP 7 and may serve as a ground for other
+data structures that require advanced referencing model.
 
 
 ## Usage
@@ -14,12 +15,18 @@ as a ground for other weak data structures.
 <?php
 
 use Weak\Reference;
+use Weak\SoftReference;
 
-$obj = new stdClass();
+$obj = new class {
+    public function __destruct() {
+        echo 'Destructor called', PHP_EOL;
+    }
+};
 
-$ref = new Reference($obj, function () { echo 'Object destroyed', PHP_EOL; });
+$softref = new SoftReference($obj, function () { echo 'Object will be destroyed', PHP_EOL; });
+$weakref = new Reference($obj, function () { echo 'Object destroyed', PHP_EOL; });
 
-$obj = null; // outputs "Object destroyed"
+$obj = null; // outputs "Object will be destroyed", "Destructor called", "Object destroyed" in this specific order.
 ```
 
 
@@ -29,13 +36,15 @@ This extension adds `Weak` namespace and all entities are created inside it.
 
 There are no INI setting or constants provided by this extension.
 
-Brief docs about [`Weak\Reference` class](./stubs/weak/Reference.php) and [functions](./stubs/weak/functions.php)
+Brief docs about classes and [functions](./stubs/weak/functions.php)
 may be seen in [stub files](./stubs/weak).
 
 Short list if what provided by this extension is:
 
-  - `class Weak\Reference`
-  - `class Weak\NotifierException extend Exception`
+  - `abstract class Weak\AbstractReference` *may not be subclassed directly* [doc](./stubs/weak/AbstractReference.php)
+  - `class Weak\SoftReference extends AbstractReference` [doc](./stubs/weak/SoftReference.php)
+  - `class Weak\Reference extends AbstractReference` [doc](./stubs/weak/Reference.php)
+  - `class Weak\NotifierException extend Exception` [doc](./stubs/weak/NotifierException.php)
   - `function Weak\refcounted()`
   - `function Weak\refcount()`
   - `function Weak\softrefcounted()`
@@ -47,6 +56,13 @@ Short list if what provided by this extension is:
   - `function Weak\object_handle()`
   - `function Weak\is_obj_destructor_called()`
 
+### References
+
+There are two type of reference provided by this extension: `SoftReference` and `Reference`. The main difference is that
+`SoftReference` call it notifier before referent object will be destructed which allows to prevent object be destroyed,
+while `Reference` call it notifier after referent object was destructed.
+
+Note: What this extension provides aren't quite actual soft and weak references, but it comes close for most use cases.
 
 ### Notifiers
 
@@ -57,14 +73,14 @@ will return `null` (unless rare case when object refcount get incremented in des
 somewhere else).
 
 If object destructor or one or more notifiers throw exception, all further notifier callbacks will be called as if
-that exception was thrown inside `try-catch` block. In case one or more exception was thrown, `Weak\NotifierException`
+that exception was thrown inside `try-catch` block. In case one or more exceptions were thrown, `Weak\NotifierException`
 will be thrown and all thrown exceptions will be available via `Weak\NotifierException::getExceptions()` method.
 
 
 ### Cloning
 
-When `Weak\Reference` cloned, notifier cloned too, so when tracking object destroyed, both notifier will be called, but
-they will be invoked with different `Weak\Reference` objects.
+When reference is cloned, notifier is cloned too, so when tracked object destroyed, both notifier will be called,
+but they will be invoked with different reference objects.
 
 ```php
 <?php
@@ -105,14 +121,14 @@ $obj = null; // outputs "Own notifier called" and then "Object destroyed"
 
 ### Serializing
 
-Serializing `Weak\Reference` is prohibited. Attempting to implement the `Serializable` interface will lead to a
+Serializing reference object is prohibited. Attempting to implement the `Serializable` interface will lead to a
 fatal error.
 
 
 ## Stub files
 
-If you are also using Composer, it is recommended that you add the [php-weak-stub](https://github.com/pinepain/php-weak-stubs)
-package as a dev-mode requirement. This provides skeleton definitions and annotations to enable support for auto-completion
+If you are also using Composer, it is recommended to add the [php-weak-stub](https://github.com/pinepain/php-weak-stubs)
+package as a dev-mode requirement. It provides skeleton definitions and annotations to enable support for auto-completion
 in your IDE and other code-analysis tools.
 
     composer require --dev pinepain/php-weak-stubs
@@ -141,7 +157,7 @@ To install extension globally run
 
     # sudo make install
 
-You will need to copy the extension config to your php dir, here is example for Ubuntu with PHP 7 from
+You will need to copy the extension config to your php dir, here is example for Ubuntu with PHP 7.0 from
 [Ondřej Surý's PPA for PHP](https://launchpad.net/~ondrej/+archive/ubuntu/php):
 
     # sudo cp provision/php/weak.ini /etc/php/mods-available/
@@ -160,23 +176,17 @@ You may also want to add php-weak extension as a [composer.json dependency](http
 ## Internals
 
 `Weak\Reference` class is implemented by storing tracked object handlers and then wrapping it original `dtor_obj` handler 
-with custom one, which meta-code is:
+with a custom one, which meta-code is:
 
 ```php
 $exceptions = [];
 
-try {
-    run_original_dtor_obj($object);
-} catch(Throwable $e) {
-    $exceptions[] = $e;
-}
-
-foreach($weak_references as $weak_ref_object_handle => $weak_reference) {
+foreach($soft_references as $soft_ref_object_handle => $soft_reference) {
     if (is_array($weak_reference->notifier)) {
-        $weak_reference->notifier[] = $weak_reference;
-    } elseif (is_callable($weak_reference->notifier)) {
+        $soft_reference->notifier[] = $weak_reference;
+    } elseif (is_callable($soft_reference->notifier)) {
         try {
-            $weak_reference->notifier($weak_reference);
+            $soft_reference->notifier($weak_reference);
         } catch(Throwable $e) {
             $exceptions[] = $e;
         }
@@ -186,11 +196,38 @@ foreach($weak_references as $weak_ref_object_handle => $weak_reference) {
 if ($exceptions) {
     throw new Weak\NotifierException('One or more exceptions thrown during notifiers calling', $exceptions);
 }
+
+if (refcount($object) == 1) {
+    try {
+        run_original_dtor_obj($object);
+    } catch(Throwable $e) {
+        $exceptions[] = $e;
+    }
+
+    foreach($weak_references as $weak_ref_object_handle => $weak_reference) {
+        if (is_array($weak_reference->notifier)) {
+            $weak_reference->notifier[] = $weak_reference;
+        } elseif (is_callable($weak_reference->notifier)) {
+            try {
+                $weak_reference->notifier($weak_reference);
+            } catch(Throwable $e) {
+                $exceptions[] = $e;
+            }
+        }
+    }
+
+    if ($exceptions) {
+        throw new Weak\NotifierException('One or more exceptions thrown during notifiers calling', $exceptions);
+    }
+} else {
+    // required while internally PHP GC mark object as it dtor was called before calling dtor
+    mark_object_as_no_destructor_was_called($object);
+}
 ```
 
 ## Development and testing
 
-This extension shipped with Vagrant file which provides basic environment for development and testing purposes. 
+This extension shipped with Vagrant file which provides basic environment for development and testing purposes.
 To start it, just type `vagrant up` and then `vagrant ssh` in php-weak directory.
 
 Services available out of the box are:
@@ -208,12 +245,14 @@ between large variety of PHP versions.
 
 ## Reference:
 
+  [Soft reference on Wikipedia](https://en.wikipedia.org/wiki/Soft_reference)
   [Weak reference on Wikipedia](https://en.wikipedia.org/wiki/Weak_reference)
 
 #### In other languages:
 
 ##### Java:
 
+  - [Class `SoftReference<T>`](https://docs.oracle.com/javase/7/docs/api/java/lang/ref/SoftReference.html)
   - [Class `WeakReference<T>`](https://docs.oracle.com/javase/7/docs/api/java/lang/ref/WeakReference.html)
   - [Guidelines for using the Java 2 reference classes](http://www.ibm.com/developerworks/library/j-refs/)
   - [Strong, Soft, Weak and Phantom References](http://neverfear.org/blog/view/150/Strong_Soft_Weak_and_Phantom_References_Java)

php_weak_reference.c

@@ -22,8 +22,11 @@
 #include "ext/spl/spl_observer.h"
 #endif
 
-zend_class_entry *php_weak_reference_class_entry;
-#define this_ce php_weak_reference_class_entry
+zend_class_entry *php_weak_abstract_reference_class_entry;
+zend_class_entry *php_weak_soft_reference_class_entry;
+zend_class_entry *php_weak_weak_reference_class_entry;
+
+#define this_ce php_weak_abstract_reference_class_entry
 
 zend_object_handlers php_weak_reference_object_handlers;
 
@@ -349,6 +352,26 @@ php_weak_referent_t *php_weak_referent_get_or_create(zval *referent_zv) /* {{{ *
     return referent;
 } /* }}} */
 
+void php_weak_soft_reference_attach(php_weak_reference_t *reference, php_weak_referent_t *referent) /* {{{ */
+{
+    reference->referent = referent;
+    zend_hash_index_add_ptr(&referent->soft_references, (zend_ulong) Z_OBJ_HANDLE_P(&reference->this_ptr), reference);
+} /* }}} */
+
+void php_weak_soft_reference_unregister(php_weak_reference_t *reference) /* {{{ */
+{
+    zend_hash_index_del(&reference->referent->soft_references, (zend_ulong) Z_OBJ_HANDLE_P(&reference->this_ptr));
+} /* }}} */
+
+void php_weak_soft_reference_maybe_unregister(php_weak_reference_t *reference) /* {{{ */
+{
+    if (NULL == reference->referent) {
+        return;
+    }
+
+    php_weak_soft_reference_unregister(reference);
+} /* }}} */
+
 void php_weak_reference_attach(php_weak_reference_t *reference, php_weak_referent_t *referent) /* {{{ */
 {
     reference->referent = referent;
@@ -483,7 +506,43 @@ static void php_weak_reference_dtor(zend_object *object) /* {{{ */
     zend_objects_destroy_object(object);
 } /* }}} */
 
-static zend_object *php_weak_reference_ctor(zend_class_entry *ce)  /* {{{ */
+static zend_object *php_weak_abstract_reference_ctor(zend_class_entry *ce)  /* {{{ */
+{
+    php_weak_reference_t *reference;
+
+    reference = (php_weak_reference_t *) ecalloc(1, sizeof(php_weak_reference_t) + zend_object_properties_size(ce));
+
+    zend_object_std_init(&reference->std, ce);
+    object_properties_init(&reference->std, ce);
+
+    reference->std.handlers = &php_weak_reference_object_handlers;
+
+    reference->register_reference = NULL;
+    reference->unregister_reference = NULL;
+
+    zend_throw_error(NULL, "%s class may not be subclassed directly", ZSTR_VAL(this_ce->name));
+
+    return &reference->std;
+} /* }}} */
+
+static zend_object *php_weak_soft_reference_ctor(zend_class_entry *ce)  /* {{{ */
+{
+    php_weak_reference_t *reference;
+
+    reference = (php_weak_reference_t *) ecalloc(1, sizeof(php_weak_reference_t) + zend_object_properties_size(ce));
+
+    zend_object_std_init(&reference->std, ce);
+    object_properties_init(&reference->std, ce);
+
+    reference->std.handlers = &php_weak_reference_object_handlers;
+
+    reference->register_reference = php_weak_soft_reference_attach;
+    reference->unregister_reference = php_weak_soft_reference_maybe_unregister;
+
+    return &reference->std;
+} /* }}} */
+
+static zend_object *php_weak_weak_reference_ctor(zend_class_entry *ce)  /* {{{ */
 {
     php_weak_reference_t *reference;
 
@@ -507,7 +566,7 @@ static zend_object *php_weak_reference_clone_obj(zval *object) /* {{{ */
 
     old_object = Z_OBJ_P(object);
 
-    new_object = php_weak_reference_ctor(old_object->ce);
+    new_object = old_object->ce->create_object(old_object->ce);
 
     php_weak_reference_t *old_reference = php_weak_reference_fetch_object(old_object);
     php_weak_reference_t *new_reference = php_weak_reference_fetch_object(new_object);
@@ -689,7 +748,7 @@ ZEND_BEGIN_ARG_INFO_EX(arginfo_weak_reference_notifier, ZEND_SEND_BY_VAL, ZEND_R
 ZEND_END_ARG_INFO()
 
 
-static const zend_function_entry php_weak_reference_methods[] = { /* {{{ */
+static const zend_function_entry php_weak_abstract_reference_methods[] = { /* {{{ */
         PHP_ME(WeakReference, __construct, arginfo_weak_reference___construct, ZEND_ACC_PUBLIC | ZEND_ACC_CTOR)
 
         PHP_ME(WeakReference, get, arginfo_weak_reference_get, ZEND_ACC_PUBLIC)
@@ -699,14 +758,23 @@ static const zend_function_entry php_weak_reference_methods[] = { /* {{{ */
         PHP_FE_END
 }; /* }}} */
 
+static const zend_function_entry php_weak_weak_reference_methods[] = { /* {{{ */
+        PHP_FE_END
+}; /* }}} */
+
+static const zend_function_entry php_weak_soft_reference_methods[] = { /* {{{ */
+        PHP_FE_END
+}; /* }}} */
+
 
 PHP_MINIT_FUNCTION (php_weak_reference) /* {{{ */
 {
     zend_class_entry ce;
 
-    INIT_NS_CLASS_ENTRY(ce, PHP_WEAK_NS, "Reference", php_weak_reference_methods);
+    INIT_NS_CLASS_ENTRY(ce, PHP_WEAK_NS, "AbstractReference", php_weak_abstract_reference_methods);
     this_ce = zend_register_internal_class(&ce);
-    this_ce->create_object = php_weak_reference_ctor;
+    this_ce->ce_flags |= ZEND_ACC_EXPLICIT_ABSTRACT_CLASS;
+    this_ce->create_object = php_weak_abstract_reference_ctor;
     this_ce->serialize = zend_class_serialize_deny;
     this_ce->unserialize = zend_class_unserialize_deny;
 
@@ -720,6 +788,14 @@ PHP_MINIT_FUNCTION (php_weak_reference) /* {{{ */
     php_weak_reference_object_handlers.get_debug_info = php_weak_get_debug_info;
     php_weak_reference_object_handlers.compare_objects = php_weak_compare_objects;
 
+    INIT_NS_CLASS_ENTRY(ce, PHP_WEAK_NS, "SoftReference", php_weak_weak_reference_methods);
+    php_weak_soft_reference_class_entry = zend_register_internal_class_ex(&ce, php_weak_abstract_reference_class_entry);
+    php_weak_soft_reference_class_entry->create_object = php_weak_soft_reference_ctor;
+
+    INIT_NS_CLASS_ENTRY(ce, PHP_WEAK_NS, "Reference", php_weak_weak_reference_methods);
+    php_weak_weak_reference_class_entry = zend_register_internal_class_ex(&ce, php_weak_abstract_reference_class_entry);
+    php_weak_weak_reference_class_entry->create_object = php_weak_weak_reference_ctor;
+
     return SUCCESS;
 } /* }}} */
 

php_weak_reference.h

@@ -21,7 +21,9 @@
 #include "TSRM.h"
 #endif
 
-extern zend_class_entry *php_weak_reference_class_entry;
+extern zend_class_entry *php_weak_abstract_reference_class_entry;
+extern zend_class_entry *php_weak_soft_reference_class_entry;
+extern zend_class_entry *php_weak_weak_reference_class_entry;
 
 
 typedef struct _php_weak_referent_t php_weak_referent_t;