1 //===-- SWIG Interface for SBEvent ------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 namespace lldb {
10 
11 class SBBroadcaster;
12 
13 %feature("docstring",
14 "API clients can register to receive events.
15 
16 For example, check out the following output: ::
17 
18     Try wait for event...
19     Event description: 0x103d0bb70 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = running}
20     Event data flavor: Process::ProcessEventData
21     Process state: running
22 
23     Try wait for event...
24     Event description: 0x103a700a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = stopped}
25     Event data flavor: Process::ProcessEventData
26     Process state: stopped
27 
28     Try wait for event...
29     Event description: 0x103d0d4a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = exited}
30     Event data flavor: Process::ProcessEventData
31     Process state: exited
32 
33     Try wait for event...
34     timeout occurred waiting for event...
35 
36 from test/python_api/event/TestEventspy: ::
37 
38     def do_listen_for_and_print_event(self):
39         '''Create a listener and use SBEvent API to print the events received.'''
40         exe = os.path.join(os.getcwd(), 'a.out')
41 
42         # Create a target by the debugger.
43         target = self.dbg.CreateTarget(exe)
44         self.assertTrue(target, VALID_TARGET)
45 
46         # Now create a breakpoint on main.c by name 'c'.
47         breakpoint = target.BreakpointCreateByName('c', 'a.out')
48 
49         # Now launch the process, and do not stop at the entry point.
50         process = target.LaunchSimple(None, None, os.getcwd())
51         self.assertTrue(process.GetState() == lldb.eStateStopped,
52                         PROCESS_STOPPED)
53 
54         # Get a handle on the process's broadcaster.
55         broadcaster = process.GetBroadcaster()
56 
57         # Create an empty event object.
58         event = lldb.SBEvent()
59 
60         # Create a listener object and register with the broadcaster.
61         listener = lldb.SBListener('my listener')
62         rc = broadcaster.AddListener(listener, lldb.SBProcess.eBroadcastBitStateChanged)
63         self.assertTrue(rc, 'AddListener successfully retruns')
64 
65         traceOn = self.TraceOn()
66         if traceOn:
67             lldbutil.print_stacktraces(process)
68 
69         # Create MyListeningThread class to wait for any kind of event.
70         import threading
71         class MyListeningThread(threading.Thread):
72             def run(self):
73                 count = 0
74                 # Let's only try at most 4 times to retrieve any kind of event.
75                 # After that, the thread exits.
76                 while not count > 3:
77                     if traceOn:
78                         print('Try wait for event...')
79                     if listener.WaitForEventForBroadcasterWithType(5,
80                                                                    broadcaster,
81                                                                    lldb.SBProcess.eBroadcastBitStateChanged,
82                                                                    event):
83                         if traceOn:
84                             desc = lldbutil.get_description(event))
85                             print('Event description:', desc)
86                             print('Event data flavor:', event.GetDataFlavor())
87                             print('Process state:', lldbutil.state_type_to_str(process.GetState()))
88                             print()
89                     else:
90                         if traceOn:
91                             print 'timeout occurred waiting for event...'
92                     count = count + 1
93                 return
94 
95         # Let's start the listening thread to retrieve the events.
96         my_thread = MyListeningThread()
97         my_thread.start()
98 
99         # Use Python API to continue the process.  The listening thread should be
100         # able to receive the state changed events.
101         process.Continue()
102 
103         # Use Python API to kill the process.  The listening thread should be
104         # able to receive the state changed event, too.
105         process.Kill()
106 
107         # Wait until the 'MyListeningThread' terminates.
108         my_thread.join()") SBEvent;
109 class SBEvent
110 {
111 public:
112     SBEvent();
113 
114     SBEvent (const lldb::SBEvent &rhs);
115 
116     %feature("autodoc",
117     "__init__(self, int type, str data) -> SBEvent (make an event that contains a C string)"
118     ) SBEvent;
119     SBEvent (uint32_t event, const char *cstr, uint32_t cstr_len);
120 
121     ~SBEvent();
122 
123     bool
124     IsValid() const;
125 
126     explicit operator bool() const;
127 
128     const char *
129     GetDataFlavor ();
130 
131     uint32_t
132     GetType () const;
133 
134     lldb::SBBroadcaster
135     GetBroadcaster () const;
136 
137     const char *
138     GetBroadcasterClass () const;
139 
140     bool
141     BroadcasterMatchesRef (const lldb::SBBroadcaster &broadcaster);
142 
143     void
144     Clear();
145 
146     static const char *
147     GetCStringFromEvent (const lldb::SBEvent &event);
148 
149     bool
150     GetDescription (lldb::SBStream &description) const;
151 };
152 
153 } // namespace lldb
154