Re: [patch] Implement post_event for Python scripts.

[Phil Muldoon <pmuldoon@redhat.com>]

On 30/07/10 22:42, Tom Tromey wrote:
>>>>>> "Joel" == Joel Brobecker <brobecker@adacore.com> writes:
> 
>>> Providing an example of a multi-threaded python script using
>>> post_event would be too complex for the manual (I'm not sure that was
>>> what you wanted anyway).  I provided a small example that shows usage.
>>> Is this okay?
> 
> Joel> I'm just trying to figure out how this feature can be useful, and
> Joel> in particular when the callbacks are triggered. Perhaps, rather than
> Joel> an example, what we need is a section that describes the event loop
> Joel> and when it is queried.


It's not useful to single-threaded scenarios (which I think are
going to be the vast number of applications of Python scripting).  For
multi-threaded scenarios (say a UI running on top of GDB that has its
own UI thread and event-loop) this is the only thread-safe way to
interact with GDB.  Describing the GDB even-loop would seem to be more
the province of an internals manual.  That being said, I take your point.


> Tom> For the purposes of post_event, I think it is probably sufficient to say
> Tom> that the callback will be executed in the main thread "sometime".  I
> Tom> don't think we can really provide anything more concrete than that
> Tom> anyhow.

I wrote up a multi-threaded example, but it is still a very basic
shell of an example.  To really show a useful  example it would require
loading an inferior, etc., and that would probably be too in-depth for
the manual

Cheers,

Phil

--


diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 03b59a3..77e21f2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -20533,6 +20533,45 @@ compute values, for example, it is the only way to get the value of a
 convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
 @end defun
 
+@findex gdb.post_event
+@defun post_event event
+Put @var{event}, a callable object taking no arguments, into
+@value{GDBN}'s internal event queue.  This callable will be invoked at
+some later point, during @value{GDBN}'s event processing.  Events
+posted using @code{post_event} will be run in the order in which they
+were posted; however, there is no way to know when they will be
+processed relative to other events inside @value{GDBN}.
+
+@value{GDBN} is not thread-safe.  If your Python program uses multiple
+threads, you must be careful to only call @value{GDBN}-specific
+functions in the main @value{GDBN} thread.  @code{post_event} ensures
+this. For example:
+
+@smallexample
+(@value{GDBP}) python
+>import threading
+>
+>class Writer():
+> def __init__(self, message):
+>        self.message = message;
+> def __call__(self):
+>        gdb.write(self.message)
+>
+>class MyThread1 (threading.Thread):
+> def run (self):
+>        gdb.post_event(Writer("Hello "))
+>
+>class MyThread2 (threading.Thread):
+> def run (self):
+>        gdb.post_event(Writer("World\n"))
+>
+>MyThread1().start()
+>MyThread2().start()
+>end
+(@value{GDBP}) Hello World
+@end smallexample
+@end defun
+
 @findex gdb.write
 @defun write string
 Print a string to @value{GDBN}'s paginated standard output stream.