Changeset 3670

Show
Ignore:
Timestamp:
18/11/08 20:29:19 (7 weeks ago)
Author:
dmeyer
Message:

doc update

Location:
trunk/base
Files:
4 modified

Legend:

Unmodified
Added
Removed

  • trunk/base/doc/notifier/mainloop.rst

    r3634 r3670  
    4040right now, you should use the kaa main loop. 
    4141 
    42 GTK 
    43 --- 
     42 
     43GObject / GTK Integration 
     44------------------------- 
    4445 
    4546The generic notifier is compatible with the GTK/Glib mainloop and kaa 
    … …  
    4950force the notifier loop to use GTK/Glib by calling init:: 
    5051 
    51     import kaa.notifier 
    52     kaa.notifier.init('gtk') 
     52    import kaa 
     53    kaa.main.select_notifier('gtk') 
    5354 
    5455This will the the GTK mainloop (the GTK mainloop is based on the glib 
    … …  
    5960of packages requiring pyNotifier and not kaa.notifier is possible. 
    6061 
    61 Twisted 
    62 ------- 
     62A different approuch is to use the generic mainloop and start the 
     63gobject mainloop in a thread. This may be useful when one loop is 
     64extremly timing depended and it is a bad idea to block for even a 
     65short time. As an example, kaa.candy uses this to keep the gobject 
     66loop small and the animations alive even when the real mainloop is 
     67very busy. 
     68 
     69.. autofunction:: kaa.gobject_set_threaded 
     70 
     71Note that callbacks from the gobject mainloop are called in that loop 
     72and not the kaa mainloop. Make sure you decorate the mainloop with the 
     73threaded decorator if necessary. For details about thread support see 
     74:ref:`threads`. The `threaded` decorator can be used to force 
     75execution of a function in the gobject mainloop. Use `kaa.GOBJECT` as 
     76thread name:: 
     77 
     78  import kaa 
     79 
     80  @kaa.threaded(kaa.MAINTHREAD) 
     81  def executed_in_kaa_mainloop(): 
     82      ... 
     83 
     84  @kaa.threaded(kaa.GOBJECT) 
     85  def executed_in_gobject_mainloop(): 
     86      ... 
     87 
     88  kaa.main.select_notifier('generic') 
     89  kaa.gobject_set_threaded() 
     90  kaa.main.run() 
     91 
     92 
     93Twisted Integration 
     94------------------- 
    6395 
    6496Kaa.notifier defines a Twisted reactor to integrate the Twisted 
    6597mainloop into the kaa mainloop. After installing the reactor you can 
    66 either run kaa.main() or reactor.run() to start the mainloop. Due to 
    67 the internal design of Twisted you can not stop the mainloop from 
    68 Twisted callbacks by calling sys.exit() or kaa.notifier.shutdown(), 
    69 you need to call reactor.stop(). From kaa callbacks sys.exit() and 
    70 kaa.notifier.stop() is supported:: 
     98either run kaa.main.run() or reactor.run() to start the mainloop. Due 
     99to the internal design of Twisted you can not stop the mainloop from 
     100Twisted callbacks by calling sys.exit() or kaa.main.shutdown(), you 
     101need to call reactor.stop(). From kaa callbacks sys.exit() and 
     102kaa.main.stop() is supported:: 
    71103 
    72104    # install special kaa reactor 
    73105    import kaa.notifier.reactor 
    74106    kaa.notifier.reactor.install() 
    75      
     107 
    76108    # get reactor 
    77109    from twisted.internet import reactor 
    78      
     110 
    79111    # add callbacks to Twisted or kaa.notifier 
    80112    # see test/twisted_in_kaa.py in the kaa.base package 
    81      
    82     # you can either call kaa.main() or reactor.run() 
    83     kaa.main() 
     113 
     114    # you can either call kaa.main.run() or reactor.run() 
     115    kaa.main.run() 
    84116 
    85117The Twisted reactor will work with any kaa.notifier backend (generic 
    … …  
    92124    # get reactor 
    93125    from twisted.internet import reactor 
    94      
    95     import kaa.notifier 
    96     kaa.notifier.init('twisted') 
    97      
     126 
     127    import kaa 
     128    kaa.main.select_notifier('twisted') 
     129 
    98130    # add callbacks to Twisted or kaa.notifier 
    99131    # see test/kaa_in_twisted.py in the kaa.base package 
    100      
     132 
    101133    # run Twisted mainloop 
    102134    reactor.run() 
     135 
    103136 
    104137Other mainloops 
    … …  
    123156The following example will integrate the kaa mainloop in the normal 
    124157Twisted reactor. In this case the Twisted mainloop is running, 
    125 kaa.main() should not be called:: 
     158kaa.main.run() should not be called:: 
    126159 
    127160    # get reactor 
    128161    from twisted.internet import reactor 
    129      
     162 
    130163    # start thread based mainloop and add Twisted callback 
    131164    import kaa.notifier 
    132     kaa.notifier.init('thread', handler = reactor.callFromThread,  
     165    kaa.notifier.init('thread', handler = reactor.callFromThread, 
    133166                      shutdown = reactor.stop) 
    134      
     167 
    135168    # add callbacks to Twisted or kaa.notifier 
    136169    # see test/kaa_in_twisted.py in the kaa.base package 
    137      
     170 
    138171    # run Twisted mainloop 
    139172    reactor.run() 

  • trunk/base/doc/notifier/threads.rst

    r3668 r3670  
     1.. _threads: 
     2 
    13Thread Support 
    24============== 
    35 
    4 FIXME: this section is just copied from the Wiki 
     6.. autofunction:: kaa.is_mainthread 
    57 
    6 ThreadCallback 
    7 -------------- 
     8.. function:: kaa.main.wakeup() 
     9 
     10   Wake up main thread. A thread can use this function to wake up a 
     11   mainloop waiting on a select. 
     12 
     13 
     14Callback Classes for Threads 
     15---------------------------- 
    816 
    917Kaa provides a ThreadCallback class which can be used to invoke a 
    … …  
    4250  print cb(3).wait() 
    4351 
    44 As a rule of thumb, if you have a function that must always be called 
    45 in the main thread, you would use @kaa.threaded(kaa.MAINTHREAD) as 
    46 mentioned above, if you need to decide case-by-case, don't decorate it 
    47 and use MainThreadCallback when needed. 
    48  
    4952.. autoclass:: kaa.MainThreadCallback 
    5053 
     54 
     55.. _threaded: 
    5156 
    5257The threaded decorator 
    5358---------------------- 
    5459 
    55 Any function or method may be decorated with @kaa.threaded() which 
     60Any function or method may be decorated with `@kaa.threaded()` which 
    5661takes two optional arguments: a thread name, and a priority. If a 
    5762thread name is specified, the decorated function is wrapped in 
    5863NamedThreadCallback, and invocations of that function are queued to be 
    59 executed in a single thread. If the thread name is kaa.MAINTHREAD the 
    60 decorated function is invoked from the main thread. If no thread name 
    61 is specified, the function is wrapped in ThreadCallback so that each 
    62 invocation is executed in a separate thread. Because these callbacks 
    63 returns InProgress objects, they may be yielded from coroutines. 
     64executed in a single thread. If the thread name is `kaa.MAINTHREAD` 
     65the decorated function is invoked from the main thread. If no thread 
     66name is specified, the function is wrapped in ThreadCallback so that 
     67each invocation is executed in a separate thread. Because these 
     68callbacks returns InProgress objects, they may be yielded from 
     69coroutines. 
    6470 
    6571(This example uses Python 2.5 syntax.):: 
    … …  
    7985     print "Thread returned", result 
    8086 
    81 The @kaa.threaded decorator also supports a async kwarg, which is by 
     87The threaded decorator also supports a async kwarg, which is by 
    8288default True. When True, the decorated function returns an InProgress 
    8389object. When False, however, invocation of the function blocks until 
    … …  
    8894.. autofunction:: kaa.threaded 
    8995 
     96As a rule of thumb, if you have a function that must always be called 
     97in the main thread, you would use `@kaa.threaded(kaa.MAINTHREAD)` as 
     98mentioned above, if you need to decide case-by-case, don't decorate it 
     99and use `MainThreadCallback` when needed. 
    90100 
    91 Helper Functions 
    92 ---------------- 
    93101 
    94 .. autofunction:: kaa.is_mainthread 
    95 .. autofunction:: kaa.notifier.main.wakeup 
     102The synchronized statement 
     103-------------------------- 
     104 
    96105.. autoclass:: kaa.synchronized 
    97106 
    98 Generic Mainloop and GObject Interaction 
    99 ---------------------------------------- 
     107Some functions may be aware of threads and block simultaneous access 
     108to specific functions. For this task, kaa has a synchronized class:: 
    100109 
    101 FIXME: this section is not yet written 
     110  class Test(object): 
    102111 
    103 .. autofunction:: kaa.gobject_set_threaded 
     112      def foo(self): 
     113          #unprotected 
     114          do_something() 
     115          with kaa.synchronized(self): 
     116              # protected block 
     117              do_something_else() 
     118 
     119      @kaa.synchronized() 
     120      def bar(self, x, y): 
     121         # protected function 
     122         do_something_else() 
     123 
     124The decorator will synchronize on the actual object. Two different 
     125objects can access the same function in two threads. On the other hand 
     126it is not possible that one thread is in the protected block of `foo` 
     127and another one calling `bar`. 
     128 
     129The decorator can also be used for functions outside a class. In that 
     130case the decorator only protects this one function. If more functions 
     131should be protected against each other, a Python RLock object can be 
     132provided:: 
     133 
     134  # threading.Lock does NOT work 
     135  lock = threading.RLock() 
     136 
     137  @kaa.synchronized(lock) 
     138  def foo(): 
     139      # foo and bar synchronized 
     140      do_something() 
     141 
     142  @kaa.synchronized(lock) 
     143  def bar(x): 
     144      # foo and bar synchronized 
     145      do_something() 
     146 
     147  @kaa.synchronized() 
     148  def baz(): 
     149      # only_baz_synchronized 
     150      do_something() 
     151 

  • trunk/base/src/notifier/gobject.py

    r3668 r3670  
    7373    def set_threaded(self, mainloop=None): 
    7474        """ 
    75         Start the gobject mainloop in a thread. This function should always 
    76         be used together with the generic notifier:: 
    77  
    78           kaa.main.select_notifier('generic') 
    79           kaa.gobject_set_threaded() 
    80  
    81         It is possible to jump between the gobject and the generic 
    82         mainloop with the threaded decorator. 
     75        Start the gobject mainloop in a thread. This function should 
     76        always be used together with the generic notifier.  It is 
     77        possible to jump between the gobject and the generic mainloop 
     78        with the threaded decorator. 
    8379 
    8480        :param mainloop: the mainloop object to use a mainloop based on gobject 

  • trunk/base/src/notifier/thread.py

    r3666 r3670  
    140140class synchronized(object): 
    141141    """ 
    142     synchronized decorator and with statement similar to synchronized 
     142    synchronized decorator and `with` statement similar to synchronized 
    143143    in Java. When decorating a non-member function, a lock or any class 
    144     inheriting from object must be provided. 
     144    inheriting from object may be provided. 
     145 
     146    :param obj: object were all calls should be synchronized to. 
     147      if not provided it will be the object for member functions 
     148      or an RLock for functions. 
    145149    """ 
    146150    def __init__(self, obj=None): 
    147151        """ 
    148         Create a synchronized object. 
    149         @param obj: object were all calls should be synchronized to. 
    150            If not provided it will be the object for member functions 
    151            or an RLock for functions. 
    152         @note: when used on classes a new member C{_kaa_synchronized_lock} 
    153         will be added to that class. 
     152        Create a synchronized object. Note: when used on classes a new 
     153        member _kaa_synchronized_lock will be added to that class. 
    154154        """ 
    155155        if obj is None: 
    … …  
    208208def is_mainthread(): 
    209209    """ 
    210     Check if the current thread is the main thread 
    211  
    212     @return: True if the caller is in the main thread right now 
     210    Return True if the current thread is the main thread 
    213211    """ 
    214212    # If threading module is None, assume main thread.  (Silences pointless