<?php

/**

 * Multi-threading (well sort of) tools

 * 

 * Greyhound - real web management for Amarok

 * Copyright (C) 2008 Dan Fuhry

 *

 * This program is Free Software; you can redistribute and/or modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied

 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for details.

 */

require_once('json.php');

/**

 * Global signal handler for SIGCHLD.

 */

function Threader_SigChld()

{

  global $threader_instances;

  foreach ( $threader_instances as &$mt )

  {

    if ( is_object($mt) )

    {

      $mt->event_sigchld();

    }

  }

}

/**

 * Global signal handler for SIGUSR2.

 */

function Threader_SigUsr2()

{

  global $threader_instances;

  foreach ( $threader_instances as &$mt )

  {

    if ( is_object($mt) )

    {

      $parchild = $mt->is_child() ? 'child' : 'parent';

      $mt->event_sigusr2();

    }

  }

}

/**

 * List of Threader instances. Needed for global handling of signals.

 * @var array

 */

global $threader_instances;

$threader_instances = array();

/**

 * Tools for emulating multi-threaded operation in PHP scripts.

 * @package Amarok

 * @subpackage WebControl

 * @author Dan Fuhry

 * @license GNU General Public License <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>

 */

class Threader

{

  /**

   * Return value of fork() if the process is a child.

   * @const int

   */

  const FORK_CHILD = -1;

  /**

   * Set to true if this is a child process. No exceptions.

   * @var bool

   * @access private

   */

  private $is_child = false;

  /**

   * Sockets for inter-process communication.

   * @var array

   * @access private

   */

  protected $ipc_sockets = array();

  /**

   * Socket for communication with the parent. Obviously only used after calling fork().

   * @var resource

   * @access private

   */

  protected $parent_sock = false;

  /**

   * Services_JSON instance.

   * @var object

   * @access private

   */

  protected $json = false;

  /**

   * PID of the parent process.

   * @var int

   * @access private

   */

  protected $parent_pid = 1;

  /**

   * List of actions for IPC events.

   * @var array

   * @access private

   */

  protected $ipc_actions = array();

  /**

   * Constructor. Sets up signal handlers. Nothing to see here, move along.

   */

  public function __construct()

  {

    global $threader_instances;

    declare(ticks=1);

    $threader_instances[] =& $this;

    pcntl_signal(SIGUSR2, 'Threader_SigUsr2');

    pcntl_signal(SIGCHLD, 'Threader_SigChld');

    $this->json = new Services_JSON(SERVICES_JSON_LOOSE_TYPE);

    $this->parent_pid = getmypid();

  }

  /**

   * Forks the current process. See your system's fork(2) man page for details.

   * @return int FORK_CHILD if child process, PID of child if parent process. Returns false on failure.

   */

  public function fork()

  {

    // create our new sockets for IPC

    $socket_pair = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);

    // fork (emoticon of the day: --<E)

    $fork_result = pcntl_fork();

    if ( $fork_result == -1 )

    {

      // fork failed.

      return false;

    }

    else if ( $fork_result )

    {

      // we are the parent - register the child

      fclose($socket_pair[0]);

      $this->ipc_sockets[$fork_result] = $socket_pair[1];

      return $fork_result;

    }

    else

    {

      // we are the child.

      fclose($socket_pair[1]);

      $this->parent_sock = $socket_pair[0];

      $this->is_child = true;

      return FORK_CHILD;

    }

  }

  /**

   * Are we a child?

   * @return bool

   */

  public function is_child()

  {

    return $this->is_child;

  }

  /**

   * Register an action so that when it is fired over IPC, a custom function can be called.

   * @param string Action

   * @param callback Function to call

   * @return true on success, false on failure

   */

  function ipc_register($action, $callback)

  {

    if ( !is_string($action) || empty($action) || !is_callable($callback) )

    {

      return false;

    }

    $this->ipc_actions[$action] = $callback;

    return true;

  }

  /**

   * Send through an IPC event. If this is a child, it only notifies the parent; if we're the parent, all children are notified. 

   * @param array Data to be sent through. This must be an associative array containing an "action" key at minimum. If this a key "propagate" set to true, a parent that receives this will propagate the message to all children.

   * @return null

   */

  function ipc_send($data)

  {

    if ( !isset($data['action']) )

    {

      return false;

    }

    $data = $this->json->encode($data);

    if ( $this->is_child() )

    {

      fwrite($this->parent_sock, "$data\n");

      // signal the parent that we've got an event

      posix_kill($this->parent_pid, SIGUSR2);

    }

    else

    {

      // signal each child

      foreach ( $this->ipc_sockets as $pid => $socket )

      {

        fwrite($socket, "$data\n");

        posix_kill($pid, SIGUSR2);

      }

    }

    return null;

  }

  /**

   * Handler for SIGCHLD events.

   * @access private

   */

  function event_sigchld()

  {

    // this should never happen to children.

    if ( $this->is_child() )

    {

      return null;

    }

    // wait for child to exit.

    pcntl_wait($status);

    // for each child PID, kill with signal 0 (effectively, test if process is alive)

    // if posix_kill fails, it's dead so remove it from the list.

    foreach ( $this->ipc_sockets as $pid => $socket )

    {

      if ( !@posix_kill($pid, 0) )

      {

        // signal failed.

        fclose($socket);

        unset($this->ipc_sockets[$pid]);

      }

    }

  }

  /**

   * Handler for IPC events.

   * @access private

   */

  function event_sigusr2()

  {

    if ( $this->is_child() )

    {

      // this is easy - the parent sent the signal.

      $command = rtrim(fgets($this->parent_sock, 102400), "\n");

    }

    else

    {

      // since we can't find which PID sent the signal, set the timeout to a very small amount

      // of time and try to read; if we get something, awesome.

      foreach ( $this->ipc_sockets as $pid => $socket )

      {

        // 1000 microseconds = 1/80th of the time it takes you to blink.

        @stream_set_timeout($socket, 0, 1000);

        $command = rtrim(@fgets($socket, 102400), "\n");

        if ( !empty($command) )

        {

          break;

        }

      }

    }

    if ( empty($command) )

    {

      // hmm, got a sigusr2 without an incoming command. oh well, ignore.

      return null;

    }

    $command = $this->json->decode($command);

    if ( !isset($command['action']) )

    {

      // no action = no way to figure out how to handle this.

      return null;

    }

    if ( !isset($this->ipc_actions[$command['action']]) )

    {

      // action not registered

      return null;

    }

    // should we propagate this event?

    if ( !$this->is_child() && isset($command['propagate']) && $command['propagate'] === true )

    {

      $this->ipc_send($command);

    }

    // we're good

    @call_user_func($this->ipc_actions[$command['action']], $command, $this);

  }

  /**

   * Kills all child processes.

   * @access public

   */

  public function kill_all_children()

  {

    foreach ( $this->ipc_sockets as $pid => $socket )

    {

      $socklen = count($this->ipc_sockets);

      posix_kill($pid, SIGTERM);

      // wait until we are conscious of this child's death

      while ( count($this->ipc_sockets) >= $socklen )

      {

        usleep(20000);

      }

    }

  }

}

?>