"""
Abstract invoker defining the API of invoker implementations.
"""

from __future__ import division, print_function, with_statement

import abc


class BaseInvoker(object):
    """Abstract invoker managing calls to call(f, fargs)."""

    __metaclass__ = abc.ABCMeta

    @abc.abstractmethod
    def __init__(self, caller):
        pass

    @abc.abstractmethod
    def invoke(self, f, fargs, **kwargs):
        """
        Implementations of this method should have the following behavior:

        Invokes call(f, fargs) with the given function and the given arguments.
        Calls back to self.caller.on_result() for successful invokes.
        Calls back to self.caller.on_error() for unsuccessful invokes.
        Can be called asynchronously, but will block if the call can not be
        executed immediately, especially when using multiple processes/threads.
        """
        pass

    @abc.abstractmethod
    def wait(self):
        """
        Implementations of this method should have the following behavior:

        Blocks till all invoke, on_error or on_result calls are done.
        """
        pass

    @abc.abstractmethod
    def abort(self):
        """
        Implementations of this method should have the following behavior:

        Cancels all running and future tasks.
        """
        pass

@@ -404,32 +404,92 @@
 s):%0A        %22%22%22%0A
+        Invoke an objective function with given arguments.%0A%0A
         Implemen
@@ -503,38 +503,47 @@
  of this method 
-should
+are expected to
  have the follow
@@ -537,32 +537,40 @@
 ve the following
+%0A       
  behavior:%0A%0A    
@@ -578,44 +578,31 @@
    I
-nvokes call(f, fargs) with the g
+t applies the object
 ive
-n
  fun
@@ -611,82 +611,314 @@
 ion 
-and the given arguments.%0A        Calls back to self.caller.on_result() for
+%60f%60 to the arguments %60fargs%60 (usually%0A        via :func:%60orges.args.call%60). If %60f%60 can be applied right now (e.g.%0A        enough resources are available) :func:%60invoke%60 should return%0A        immediately, otherwise :func:%60invoke%60 should block until %60f%60 can be%0A        applied.%0A%0A        After %60f%60 was applied
  suc
@@ -928,69 +928,218 @@
 sful
+ly the
  invoke
-s.%0A        Calls back to self.caller.on_error() for un
+r should call%0A        :meth:%60orges.optimizer.base.BaseCaller.on_result%60 on the caller passing%0A        the result of the application, %60fargs%60 and %60kwargs%60. If the application%0A        of %60f%60 was not 
 succ
@@ -1149,172 +1149,488 @@
 ful 
+the 
 invoke
-s.%0A        Can be called asynchronously, but will block if the call can not be%0A        executed immediately, especially when using multiple processes/threads.
+r should call%0A        :meth:%60orges.optimizer.base.BaseCaller.on_error%60 passing an error,%0A        %60fargs%60 and %60kwargs%60.%0A%0A        Calls to both %60on_result%60 and %60on_error%60 and should be synchronized and%0A        thus the invoker has to wait until these methods return before calling%0A        them again.%0A%0A        :param f: Objective function%0A        :param fargs: Arguments %60f%60 should be applied to%0A        :param kwargs: Additional data arguments%0A%0A        TODO: Return value
 %0A   
@@ -1700,32 +1700,114 @@
 f):%0A        %22%22%22%0A
+        Wait until %60on_result%60 or %60on_error%60 were called for each :meth:%60invoke%60%0A%0A
         Implemen
@@ -1821,38 +1821,47 @@
  of this method 
-should
+are expected to
  have the follow
@@ -1855,32 +1855,40 @@
 ve the following
+%0A       
  behavior:%0A%0A    
@@ -1895,69 +1895,213 @@
     
-Blocks till all invoke, on_error or on_result calls are done.
+It waits until :meth:%60orges.optimizer.base.BaseCaller.on_result%60 or%0A        :meth:%60orges.optimizer.base.BaseCaller.on_error%60 were called for each%0A        call to :meth:%60invoke%60.%0A%0A        TODO: Return value
 %0A   
@@ -2172,32 +2172,94 @@
 f):%0A        %22%22%22%0A
+        Abort all current and future calls to :meth:%60invoke%60%0A%0A
         Implemen
@@ -2281,22 +2281,31 @@
  method 
-should
+are expected to
  have th
@@ -2315,16 +2315,24 @@
 ollowing
+%0A       
  behavio
@@ -2347,44 +2347,157 @@
     
-Cancels all running and future tasks
+It immediately (or rather as fast as possible) calls%0A        :meth:%60orges.optimizer.base.BaseCaller.on_error%60 for each call to%0A        :meth:%60invoke%60
 .%0A  

Improve documentation for BaseInvoker