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
9namespace lldb {
10
11class SBBroadcaster;
12
13%feature("docstring",
14"API clients can register to receive events.
15
16For example, check out the following output:
17
18Try wait for event...
19Event description: 0x103d0bb70 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = running}
20Event data flavor: Process::ProcessEventData
21Process state: running
22
23Try wait for event...
24Event description: 0x103a700a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = stopped}
25Event data flavor: Process::ProcessEventData
26Process state: stopped
27
28Try wait for event...
29Event description: 0x103d0d4a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = exited}
30Event data flavor: Process::ProcessEventData
31Process state: exited
32
33Try wait for event...
34timeout occurred waiting for event...
35
36from 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;
109class SBEvent
110{
111public:
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