[lldb-dev] Question about LLDB SBEvent C++ API

[Greg Clayton via lldb-dev]

> On Mar 14, 2020, at 4:13 PM, Rui Liu via lldb-dev <lldb-dev at lists.llvm.org> wrote:
> 
> Hi LLDB devs,
> 
> The SBEvent API has GetType() method on it, which returns a uint32_t, however I didn't find any documentation on how to interpret this uint32_t... Is there a enum for it somewhere?
> 
> There is a GetDescription() API to create a human-readable string, but I'd rather to inspect the event type programmatically.
> 
> Overall I find the API is not documented very well, which makes it quite hard to use... For example, I didn't find a place that explains what are the the possible event types and what data they carry. (I didn't even find an enum!) Are there any good resources that I might not discover yet?
> 
> Also any advice on how to use LLDB C++ API (without prior knowledge) would be much appreciated!

A good example in python can be found at:

lldb/examples/python/process_events.py

Also the lldb-vscode plug-in shows how to use the API from a C++ perspective:

lldb/tools/lldb-vscode/lldb-vscode.cpp

Events are generated by SBBroadcaster objects or internally inside of LLDB and caught using SBListener objects. Every object that can generate SBEvents have an enumeration declared in the class header file. For example in SBProcess.h we see:

class LLDB_API SBProcess {
public:
  /// Broadcaster event bits definitions.
  FLAGS_ANONYMOUS_ENUM(){eBroadcastBitStateChanged = (1 << 0),
                         eBroadcastBitInterrupt = (1 << 1),
                         eBroadcastBitSTDOUT = (1 << 2),
                         eBroadcastBitSTDERR = (1 << 3),
                         eBroadcastBitProfileData = (1 << 4),
                         eBroadcastBitStructuredData = (1 << 5)};

If you search for SBEvent in each header file you can see the event introspection functions. They are all static and take a SBEvent & argument. For example to see if an event is a  process event you can call:

static bool SBProcess::EventIsProcessEvent(const lldb::SBEvent &event);

It all depends on how many different kinds of events you sign up to listen to with your SBListener. When launching a process you _can_ provide a listener in the SBLaunchInfo or SBAttachInfo, but most people don't set one and all events delivered to the SBDebugger, which you can listen for all events from the SBTarget, SBProcess and SBThread. 

Once you determine what kind of event you have using:

static bool SBTarget::EventIsTargetEvent(const lldb::SBEvent &event);
static bool SBProcess::EventIsProcessEvent(const lldb::SBEvent &event);
static bool SBThread::EventIsThreadEvent(const lldb::SBEvent &event);
static bool SB*::EventIs*Event(const lldb::SBEvent &event);

Then you can use the enumerations in the appropriate header file to check the type and identify the event type. There are usually static functions that will help you extract more information from the event. For example for the SBProcess::eBroadcastBitStateChanged event, you can get the state from the event:

static lldb::StateType SBProcess::GetStateFromEvent(const lldb::SBEvent &event);

StateType tells you what the process state has changed to: eStateStopped, eStateRunning, eStateExited.

There definitely should be more documentation on this, but for now feel free to ask us any questions here.

Greg