1130803Smarcel@c -*-texinfo-*- 2130803Smarcel@node GDB Observers 3130803Smarcel@appendix @value{GDBN} Currently available observers 4130803Smarcel 5130803Smarcel@section Implementation rationale 6130803Smarcel@cindex observers implementation rationale 7130803Smarcel 8130803SmarcelAn @dfn{observer} is an entity which is interested in being notified 9130803Smarcelwhen GDB reaches certain states, or certain events occur in GDB. 10130803SmarcelThe entity being observed is called the @dfn{subject}. To receive 11130803Smarcelnotifications, the observer attaches a callback to the subject. 12130803SmarcelOne subject can have several observers. 13130803Smarcel 14130803Smarcel@file{observer.c} implements an internal generic low-level event 15130803Smarcelnotification mechanism. This generic event notification mechanism is 16130803Smarcelthen re-used to implement the exported high-level notification 17130803Smarcelmanagement routines for all possible notifications. 18130803Smarcel 19130803SmarcelThe current implementation of the generic observer provides support 20130803Smarcelfor contextual data. This contextual data is given to the subject 21130803Smarcelwhen attaching the callback. In return, the subject will provide 22130803Smarcelthis contextual data back to the observer as a parameter of the 23130803Smarcelcallback. 24130803Smarcel 25130803SmarcelNote that the current support for the contextual data is only partial, 26130803Smarcelas it lacks a mechanism that would deallocate this data when the 27130803Smarcelcallback is detached. This is not a problem so far, as this contextual 28130803Smarceldata is only used internally to hold a function pointer. Later on, if 29130803Smarcela certain observer needs to provide support for user-level contextual 30130803Smarceldata, then the generic notification mechanism will need to be 31130803Smarcelenhanced to allow the observer to provide a routine to deallocate the 32130803Smarceldata when attaching the callback. 33130803Smarcel 34130803SmarcelThe observer implementation is also currently not reentrant. 35130803SmarcelIn particular, it is therefore not possible to call the attach 36130803Smarcelor detach routines during a notification. 37130803Smarcel 38130803Smarcel@section @code{normal_stop} Notifications 39130803Smarcel@cindex @code{normal_stop} observer 40130803Smarcel@cindex notification about inferior execution stop 41130803Smarcel 42130803Smarcel@value{GDBN} notifies all @code{normal_stop} observers when the 43130803Smarcelinferior execution has just stopped, the associated messages and 44130803Smarcelannotations have been printed, and the control is about to be returned 45130803Smarcelto the user. 46130803Smarcel 47130803SmarcelNote that the @code{normal_stop} notification is not emitted when 48130803Smarcelthe execution stops due to a breakpoint, and this breakpoint has 49130803Smarcela condition that is not met. If the breakpoint has any associated 50130803Smarcelcommands list, the commands are executed after the notification 51130803Smarcelis emitted. 52130803Smarcel 53130803SmarcelThe following interface is available to manage @code{normal_stop} 54130803Smarcelobservers: 55130803Smarcel 56130803Smarcel@deftypefun extern struct observer *observer_attach_normal_stop (observer_normal_stop_ftype *@var{f}) 57130803SmarcelAttach the given @code{normal_stop} callback function @var{f} and 58130803Smarcelreturn the associated observer. 59130803Smarcel@end deftypefun 60130803Smarcel 61130803Smarcel@deftypefun extern void observer_detach_normal_stop (struct observer *@var{observer}); 62130803SmarcelRemove @var{observer} from the list of observers to be notified when 63130803Smarcela @code{normal_stop} event occurs. 64130803Smarcel@end deftypefun 65130803Smarcel 66130803Smarcel@deftypefun extern void observer_notify_normal_stop (void); 67130803SmarcelSend a notification to all @code{normal_stop} observers. 68130803Smarcel@end deftypefun 69130803Smarcel 70130803Smarcel 71