Introduce gdb.FinishBreakpoint in Python

	* Makefile.in (SUBDIR_PYTHON_OBS): Add py-finishbreakpoint.o.
	(SUBDIR_PYTHON_SRCS): Add python/py-finishbreakpoint.c.
	Add build rule for this file.
	* infcmd.c (print_return_value): Split to create get_return_value.
	(get_return_value): New function based on print_return_value. Handle
	case where stop_registers are not set.
	* inferior.h (get_return_value): New prototype.
	* python/py-breakpoint.c (bppy_pending_object): Make non-static.
	(gdbpy_breakpoint_created): Set is_py_finish_bp is necessary.
	(struct breakpoint_object): Move to python-internal.h
	(BPPY_REQUIRE_VALID): Likewise.
	(BPPY_SET_REQUIRE_VALID): Likewise.
	(gdbpy_breakpoint_created): Initialize is_finish_bp.
	(gdbpy_should_stop): Add  pre/post hooks before/after calling stop
	method.
	* python/python-internal.h (breakpoint_object_type): Add as extern.
	(bppy_pending_object): Likewise.
	(typedef struct breakpoint_object) Removed.
	(struct breakpoint_object): Moved from py-breakpoint.c.
	Add field is_finish_bp.
	(BPPY_REQUIRE_VALID): Moved from py-breakpoint.c.
	(BPPY_SET_REQUIRE_VALID): Likewise.
	(frame_object_to_frame_info): New prototype.
	(gdbpy_initialize_finishbreakpoints): New prototype.
	(bpfinishpy_is_finish_bp): Likewise.
	(bpfinishpy_pre_stop_hook): Likewise.
	(bpfinishpy_post_stop_hook): Likewise.
	* python/py-finishbreakpoint.c: New file.
	* python/py-frame.c(frame_object_to_frame_info): Make non-static and
	accept PyObject instead of frame_object.
	(frapy_is_valid): Don't cast to frame_object.
	(frapy_name): Likewise.
	(frapy_type): Likewise.
	(frapy_unwind_stop_reason): Likewise.
	(frapy_pc): Likewise.
	(frapy_block): Likewise.
	(frapy_function): Likewise.
	(frapy_older): Likewise.
	(frapy_newer): Likewise.
	(frapy_find_sal): Likewise.
	(frapy_read_var): Likewise.
	(frapy_select): Likewise.
	* python/python.c (gdbpy_is_stopped_at_finish_bp): New noop function.
	(_initialize_python): Add gdbpy_initialize_finishbreakpoints.
	* python/python.h: Include breakpoint.h
	(gdbpy_is_stopped_at_finish_bp): New prototype.

doc/
	* gdb.texinfo (Finish Breakpoints in Python): New subsection.
	(Python API): Add menu entry for Finish Breakpoints.

testsuite/
	* Makefile.in (EXECUTABLES): Add py-finish-breakpoint and
	py-finish-breakpoint2
	(MISCALLANEOUS): Add py-events-shlib.so and py-events-shlib-nodebug.so
	* gdb.python/py-breakpoint.exp (mult_line): Define and use variable
	instead of line number.
	* gdb.python/py-finish-breakpoint.c: New file.
	* gdb.python/py-finish-breakpoint.exp: New file.
	* gdb.python/py-finish-breakpoint.py: New file.
	* gdb.python/py-finish-breakpoint2.cc: New file.
	* gdb.python/py-finish-breakpoint2.exp: New file.
	* gdb.python/py-finish-breakpoint2.py: New file.

2 files changed, 59 insertions, 0 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 0632d096f7..0ede40bb8f 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2011-12-23  Kevin Pouget  <kevin.pouget@st.com>
+
+	Introduce gdb.FinishBreakpoint in Python.
+	* gdb.texinfo (Finish Breakpoints in Python): New subsection.
+	(Python API): Add menu entry for Finish Breakpoints.
+
 2011-12-19  Jan Kratochvil  <jan.kratochvil@redhat.com>
 
 	* gdbint.texinfo (Testsuite): Describe KFAIL and XFAIL in Writing
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4a7ae6eba6..3cd3b67c6e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21525,6 +21525,8 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
 * Symbol Tables In Python::     Python representation of symbol tables.
 * Lazy Strings In Python::      Python representation of lazy strings.
 * Breakpoints In Python::       Manipulating breakpoints using Python.
+* Finish Breakpoints in Python:: Setting Breakpoints on function return
+                                using Python.
 @end menu
 
 @node Basic Python
@@ -24359,6 +24361,57 @@ commands, separated by newlines.  If there are no commands, this
 attribute is @code{None}.  This attribute is not writable.
 @end defvar
 
+@node Finish Breakpoints in Python
+@subsubsection Finish Breakpoints
+
+@cindex python finish breakpoints
+@tindex gdb.FinishBreakpoint
+
+A finish breakpoint is a temporary breakpoint set at the return address of
+a frame, based on the @code{finish} command.  @code{gdb.FinishBreakpoint}
+extends @code{gdb.Breakpoint}.  The underlying breakpoint will be disabled 
+and deleted when the execution will run out of the breakpoint scope (i.e.@: 
+@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered).
+Finish breakpoints are thread specific and must be create with the right 
+thread selected.  
+ 
+@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]})
+Create a finish breakpoint at the return address of the @code{gdb.Frame}
+object @var{frame}.  If @var{frame} is not provided, this defaults to the
+newest frame.  The optional @var{internal} argument allows the breakpoint to
+become invisible to the user.  @xref{Breakpoints In Python}, for further 
+details about this argument.
+@end defun
+
+@defun FinishBreakpoint.out_of_scope (self)
+In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} 
+@code{return} command, @dots{}), a function may not properly terminate, and
+thus never hit the finish breakpoint.  When @value{GDBN} notices such a
+situation, the @code{out_of_scope} callback will be triggered.
+
+You may want to sub-class @code{gdb.FinishBreakpoint} and override this
+method:
+
+@smallexample
+class MyFinishBreakpoint (gdb.FinishBreakpoint)
+    def stop (self):
+        print "normal finish"
+        return True
+    
+    def out_of_scope ():
+        print "abnormal finish"
+@end smallexample 
+@end defun
+
+@defvar FinishBreakpoint.return_value
+When @value{GDBN} is stopped at a finish breakpoint and the frame 
+used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this
+attribute will contain a @code{gdb.Value} object corresponding to the return
+value of the function.  The value will be @code{None} if the function return 
+type is @code{void} or if the return value was not computable.  This attribute
+is not writable.
+@end defvar
+
 @node Lazy Strings In Python
 @subsubsection Python representation of lazy strings.