Commits

Thomas Weinert committed 9bdfb6a

Documented Carica\Io\Deferred

  • Participants
  • Parent commits c1fbfe2

Comments (0)

Files changed (1)

src/Io/Deferred.php

 
 namespace Carica\Io {
 
+  /**
+  * A deffered object implementation, allows to schedule callbacks for
+  * execution after a condition is meet or not.
+  *
+  */
   class Deferred {
 
+    /**
+     * Default state - not yet finalized
+     * @var string
+     */
     const STATE_PENDING = 'pending';
+    /**
+     * Final state, object was resolved, the action was successful
+     * @var string
+     */
     const STATE_RESOLVED = 'resolved';
+
+    /**
+     * Final state, object was rejected, the action failed
+     *
+     * @var string
+     */
     const STATE_REJECTED = 'rejected';
 
+    /**
+     * current state
+     * .
+     * @var string
+     */
     private $_state = self::STATE_PENDING;
+    /**
+     * An promise for this object
+     * .
+     * @var \Carica\Io\Deferred\Promise
+     */
     private $_promise = NULL;
 
+    /**
+     * Callbacks if the object is resolved
+     * .
+     * @var \Carica\Io\Callbacks
+     */
     private $_done = NULL;
+    /**
+     * Callbacks if the object is rejected
+     * .
+     * @var \Carica\Io\Callbacks
+     */
     private $_failed = NULL;
+    /**
+     * Callbacks if the object is notified about a progress
+     * .
+     * @var \Carica\Io\Callbacks
+     */
     private $_progress = NULL;
 
+    /**
+     * buffer for the arguments of the resolve/reject function,
+     * used to execute functions, that are added after the object was finalized
+     * .
+     * @var array
+     */
     private $_finishArguments = array();
+    /**
+     * Buffer for the last progress notification arguments, used
+     * to bring new callback up to date.
+     * .
+     * @var NULL|array
+     */
     private $_progressArguments = NULL;
 
+    /**
+     * Create object and intialize callback lists
+     */
     public function __construct() {
       $this->_done = new Callbacks();
       $this->_failed = new Callbacks();
       $this->_progress = new Callbacks();
     }
 
+    /**
+     * Add a callback that will be execute if the object is finalized with
+     * resolved or reject
+     *
+     * @param Callable $callback
+     * @return \Carica\Io\Deferred
+     */
     public function always(Callable $callback) {
       $this->_done->add($callback);
       $this->_failed->add($callback);
       return $this;
     }
 
+    /**
+     * Add a callback that will be executed if the object is resolved
+     *
+     * @param Callable $callback
+     * @return \Carica\Io\Deferred
+     */
     public function done(Callable $callback) {
       $this->_done->add($callback);
       if ($this->_state == self::STATE_RESOLVED) {
       return $this;
     }
 
+    /**
+     * Add a callback that will be eecuted if the object was rejected
+     *
+     * @param Callable $callback
+     * @return \Carica\Io\Deferred
+     */
     public function fail(Callable $callback) {
       $this->_failed->add($callback);
       if ($this->_state == self::STATE_REJECTED) {
       return $this;
     }
 
+    /**
+     * Validate if the object was finilized using reject.
+     *
+     * @return string
+     */
     public function isRejected() {
       return $this->_state = self::STATE_REJECTED;
     }
-
+
+    /**
+     * Validate if the object was finilized using resolve.
+     *
+     * @return string
+     */
     public function isResolved() {
       return $this->_state = self::STATE_RESOLVED;
     }
 
+    /**
+     * Notify the object about the progress
+     */
     public function notify() {
       if ($this->_state == self::STATE_PENDING) {
         $this->_progressArguments = func_get_args();
         call_user_func_array($this->_progress, $this->_progressArguments);
       }
+      return $this;
     }
 
     public function pipe(
       return $defer->promise();
     }
 
+    /**
+     * Add a callback that will be executed if the object is notified about progress
+     *
+     * @param Callable $callback
+     * @return \Carica\Io\Deferred
+     */
     public function progress(Callable $callback) {
       $this->_progress->add($callback);
       if (NULL !== $this->_progressArguments) {
       return $this;
     }
 
+    /**
+     * Creates and returns a promise attached to this object, a promise is used to
+     * attach callbacks and validate the status. But has no methods to change the status.
+     *
+     * @return \Carica\Io\Deferred\Promise
+     */
     public function promise() {
       if (NULL === $this->_promise) {
         $this->_promise = new Deferred\Promise($this);
       return $this->_promise;
     }
 
+    /**
+     * Finalize the object and set the status to rejected - the action has failed.
+     * This will execute all callbacks attached with fail() or always()
+     *
+     * @return \Carica\Io\Deferred
+     */
     public function reject() {
       if ($this->_state == self::STATE_PENDING) {
         $this->_finishArguments = func_get_args();
         $this->_state = self::STATE_REJECTED;
         call_user_func_array($this->_failed, $this->_finishArguments);
       }
+      return $this;
     }
-
+
+    /**
+     * Finalize the object and set the status to rejected - the action was successful.
+     * This will execute all callbacks attached with done() or always()
+     *
+     * @return \Carica\Io\Deferred
+     */
     public function resolve() {
       if ($this->_state == self::STATE_PENDING) {
         $this->_finishArguments = func_get_args();
         $this->_state = self::STATE_RESOLVED;
         call_user_func_array($this->_done, $this->_finishArguments);
       }
+      return $this;
     }
 
+    /**
+     * Return the state string. Here are constants for each state, too.
+     *
+     * @return string
+     */
     public function state() {
       return $this->_state;
     }