/*                     __                                               *\
**     ________ ___   / /  ___     Scala API                            **
**    / __/ __// _ | / /  / _ |    (c) 2005-2009, LAMP/EPFL             **
**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
** /____/\___/_/ |_/____/_/ | |                                         **
**                          |/                                          **
\*                                                                      */

package scala.actors

/**
 * adds methods to AbstractActor that will be implemented in concrete actors
 * @author Erik Engbrecht
 */
trait BaseActor extends AbstractActor {
  /**
   * Receives a message from this actor's mailbox.
   * <p>
   * This method never returns. Therefore, the rest of the computation
   * has to be contained in the actions of the partial function.
   *
   * @param  f    a partial function with message patterns and actions
   * @throws InvalidStateForOperation if the actor is not in a Running state
   */
  def react(f: PartialFunction[Any, Unit]): Nothing

  /**
   * Receives a message from this actor's mailbox within a certain
   * time span.
   * <p>
   * This method never returns. Therefore, the rest of the computation
   * has to be contained in the actions of the partial function.
   *
   * @param  msec the time span before timeout
   * @param  f    a partial function with message patterns and actions
   * @throws InvalidStateForOperation if the actor is not in a Running state
   */
  def reactWithin(msec: Long)(f: PartialFunction[Any, Unit]): Nothing

  /**
   * Receives a message from the mailbox of
   * <code>self</code>. Blocks if no message matching any of the
   * cases of <code>f</code> can be received.
   *
   * @param  f a partial function specifying patterns and actions
   * @return   the result of processing the received message
   */
  def receive[A](f: PartialFunction[Any, A]): A

  /**
   * Receives a message from the mailbox of
   * <code>self</code>. Blocks at most <code>msec</code>
   * milliseconds if no message matching any of the cases of
   * <code>f</code> can be received. If no message could be
   * received the <code>TIMEOUT</code> action is executed if
   * specified.
   *
   * @param  msec the time span before timeout
   * @param  f    a partial function specifying patterns and actions
   * @return      the result of processing the received message
   */
  def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R

  /*def loop(body: => Unit): Nothing */

  /*def loopWhile(cond: => Boolean)(body: => Unit): Nothing */
  
  /**
   * @todo submit bug report because package qualification on protected members doesn't work
   */
  protected[actors] def mailbox: MessageQueue[Message[Any]]

  /**
   * some parts of the actors package need access to the mailbox but the
   * package access qualification doesn't work for protected, so use this
   * instead
   */
  private[actors] final def mailboxForChannel: MessageQueue[Message[Any]] = mailbox

  /**
   * Returns the number of messages in <code>self</code>'s mailbox
   *
   * @return the number of messages in <code>self</code>'s mailbox
   */
  def mailboxSize: Int

  /**
   * @todo should send be protected?
   */
  def send(msg: Any, replyTo: OutputChannel[Any]): Unit
  /**
   * Forwards <code>msg</code> to this actor (asynchronous).
   */
  def forward(msg: Any): Unit

  /**
   * reply to the sender of the last message received
   * @param msg the message to send
   * @throws ??? if no message is currently being processed
   */
  def reply(msg: Any): Unit
  /**
   * The sender of the message currently being processed.
   * If no message is being processed, this method will throw an exception.
   * @todo restrict access to sender
   */
  /*protected[actors]*/ def sender: OutputChannel[Any]

  /**
   * Receives the next message from the mailbox of the current actor
   * <code>self</code>.
   */
  def ? : Any

  /**
   * Start the actor
   */
  def start(): AbstractActor

  def freshReplyChannel: Channel[Any] = new Channel[Any](this)

  def scheduler: IScheduler //TODO: restrict access to scheduler??
}