Blame - docs/dyn/clouddebugger_v2.controller.debuggees.breakpoints.html - platform/external/python/google-api-python-client

2015-09-11 13:55:40 -0700

[diff] [blame]

76

<h2>Instance Methods</h2>

77

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

78

<code><a href="#list">list(debuggeeId, agentId=None, successOnTimeout=None, waitToken=None, x__xgafv=None)</a></code></p>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

79

<p class="firstline">Returns the list of all active breakpoints for the debuggee.</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

80

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

81

<code><a href="#update">update(debuggeeId, id, body=None, x__xgafv=None)</a></code></p>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

82

<p class="firstline">Updates the breakpoint state or mutable fields.</p>

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

83

<h3>Method Details</h3>

84

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

85

<code class="details" id="list">list(debuggeeId, agentId=None, successOnTimeout=None, waitToken=None, x__xgafv=None)</code>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

86

<pre>Returns the list of all active breakpoints for the debuggee.

87

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

88

The breakpoint specification (`location`, `condition`, and `expressions`

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

89

fields) is semantically immutable, although the field values may

90

change. For example, an agent may update the location line number

91

to reflect the actual line where the breakpoint was set, but this

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

92

doesn't change the breakpoint semantics.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

93

94

This means that an agent does not need to check if a breakpoint has changed

95

when it encounters the same breakpoint on a successive call.

96

Moreover, an agent should remember the breakpoints that are completed

97

until the controller removes them from the active list to avoid

98

setting those breakpoints again.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

99

100

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

101

debuggeeId: string, Required. Identifies the debuggee. (required)

102

agentId: string, Identifies the agent.

103

This is the ID returned in the RegisterDebuggee response.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

104

successOnTimeout: boolean, If set to `true` (recommended), returns `google.rpc.Code.OK` status and

105

sets the `wait_expired` response field to `true` when the server-selected

106

timeout has expired.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

107

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

108

If set to `false` (deprecated), returns `google.rpc.Code.ABORTED` status

109

when the server-selected timeout has expired.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

110

waitToken: string, A token that, if specified, blocks the method call until the list

111

of active breakpoints has changed, or a server-selected timeout has

112

expired. The value should be set from the `next_wait_token` field in

113

the last response. The initial value should be set to `"init"`.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

114

x__xgafv: string, V1 error format.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

115

Allowed values

116

1 - v1 error format

117

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

118

119

Returns:

120

An object of the form:

121

Jon Wayne Parrott

36e41bc

2016-02-19 16:02:29 -0800

[diff] [blame]

122

{ # Response for listing active breakpoints.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

123

"breakpoints": [ # List of all active breakpoints.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

124

# The fields `id` and `location` are guaranteed to be set on each breakpoint.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

125

{ # ------------------------------------------------------------------------------

126

# ## Breakpoint (the resource)

127

#

128

# Represents the breakpoint specification, status and results.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

129

"canaryExpireTime": "A String", # The deadline for the breakpoint to stay in CANARY_ACTIVE state. The value

130

# is meaningless when the breakpoint is not in CANARY_ACTIVE state.

131

"status": { # Represents a contextual status message. # Breakpoint status.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

132

#

133

# The status includes an error flag and a human readable message.

134

# This field is usually unset. The message can be either

135

# informational or an error message. Regardless, clients should always

136

# display the text message back to the user.

137

#

138

# Error status indicates complete failure of the breakpoint.

139

#

140

# Example (non-final state): `Still loading symbols...`

141

#

142

# Examples (final state):

143

#

144

# * `Invalid line number` referring to location

145

# * `Field f not found in class C` referring to condition

146

# The message can indicate an error or informational status, and refer to

147

# specific parts of the containing object.

148

# For example, the `Breakpoint.status` field can indicate an error referring

149

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

150

"isError": True or False, # Distinguishes errors from informational messages.

151

"description": { # Represents a message with parameters. # Status message text.

152

"parameters": [ # Optional parameters to be embedded into the message.

153

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

154

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

155

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

156

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

161

# * `Failed to load '$0' which helps debug $1 the first time it

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

162

# is loaded. Again, $0 is very important.`

163

# * `Please pay $$10 to use $0 instead of $1.`

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

164

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

165

"refersTo": "A String", # Reference to which the message applies.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

166

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

167

"state": "A String", # The current state of the breakpoint.

168

"userEmail": "A String", # E-mail address of the user that created this breakpoint

169

"action": "A String", # Action that the agent should perform when the code at the

170

# breakpoint location is hit.

171

"logLevel": "A String", # Indicates the severity of the log. Only relevant when action is `LOG`.

172

"id": "A String", # Breakpoint identifier, unique in the scope of the debuggee.

173

"location": { # Represents a location in the source code. # Breakpoint source location.

174

"path": "A String", # Path to the source file within the source context of the target binary.

175

"column": 42, # Column within a line. The first column in a line as the value `1`.

176

# Agents that do not support setting breakpoints on specific columns ignore

177

# this field.

178

"line": 42, # Line inside the file. The first line in the file has the value `1`.

179

},

180

"finalTime": "A String", # Time this breakpoint was finalized as seen by the server in seconds

181

# resolution.

182

"variableTable": [ # The `variable_table` exists to aid with computation, memory and network

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

183

# traffic optimization. It enables storing a variable once and reference

184

# it from multiple variables, including variables stored in the

185

# `variable_table` itself.

186

# For example, the same `this` object, which may appear at many levels of

187

# the stack, can have all of its data stored once in this table. The

188

# stack frame variables then would hold only a reference to it.

189

#

190

# The variable `var_table_index` field is an index into this repeated field.

191

# The stored objects are nameless and get their name from the referencing

192

# variable. The effective variable is a merge of the referencing variable

193

# and the referenced variable.

194

{ # Represents a variable or an argument possibly of a compound object type.

195

# Note how the following variables are represented:

196

#

197

# 1) A simple variable:

198

#

199

# int x = 5

200

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

201

# { name: "x", value: "5", type: "int" } // Captured variable

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

202

#

203

# 2) A compound object:

#

# struct T {

# int m1;

# int m2;

# };

# T x = { 3, 7 };

#

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

212

# name: "x",

213

# type: "T",

214

# members { name: "m1", value: "3", type: "int" },

215

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

216

# }

217

#

218

# 3) A pointer where the pointee was captured:

219

#

220

# T x = { 3, 7 };

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

221

# T* p = &x;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

222

#

223

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

224

# name: "p",

225

# type: "T*",

226

# value: "0x00500500",

227

# members { name: "m1", value: "3", type: "int" },

228

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

229

# }

230

#

231

# 4) A pointer where the pointee was not captured:

#

# T* p = new T;

#

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

236

# name: "p",

237

# type: "T*",

238

# value: "0x00400400"

239

# status { is_error: true, description { format: "unavailable" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

240

# }

241

#

242

# The status should describe the reason for the missing value,

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

243

# such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

244

#

245

# Note that a null pointer should not have members.

246

#

247

# 5) An unnamed value:

248

#

249

# int* p = new int(7);

250

#

251

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

252

# name: "p",

253

# value: "0x00500500",

254

# type: "int*",

255

# members { value: "7", type: "int" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

256

#

257

# 6) An unnamed pointer where the pointee was not captured:

258

#

259

# int* p = new int(7);

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

260

# int** pp = &p;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

261

#

262

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

263

# name: "pp",

264

# value: "0x00500500",

265

# type: "int**",

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

266

# members {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

267

# value: "0x00400400",

268

# type: "int*"

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

269

# status {

270

# is_error: true,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

271

# description: { format: "unavailable" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

# }

# }

# }

#

# To optimize computation, memory and network traffic, variables that

277

# repeat in the output multiple times can be stored once in a shared

278

# variable table and be referenced using the `var_table_index` field. The

279

# variables stored in the shared table are nameless and are essentially

280

# a partition of the complete variable. To reconstruct the complete

281

# variable, merge the referencing variable with the referenced variable.

282

#

283

# When using the shared variable table, the following variables:

284

#

285

# T x = { 3, 7 };

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

286

# T* p = &x;

287

# T& r = x;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

288

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

289

# { name: "x", var_table_index: 3, type: "T" } // Captured variables

290

# { name: "p", value "0x00500500", type="T*", var_table_index: 3 }

291

# { name: "r", type="T&", var_table_index: 3 }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

292

#

293

# { // Shared variable table entry #3:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

294

# members { name: "m1", value: "3", type: "int" },

295

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

296

# }

297

#

298

# Note that the pointer address is stored with the referencing variable

299

# and not with the referenced variable. This allows the referenced variable

300

# to be shared between pointers and references.

301

#

302

# The type field is optional. The debugger agent may or may not support it.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

303

"members": [ # Members contained or pointed to by the variable.

304

# Object with schema name: Variable

305

],

306

"status": { # Represents a contextual status message. # Status associated with the variable. This field will usually stay

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

307

# unset. A status of a single variable only applies to that variable or

308

# expression. The rest of breakpoint data still remains valid. Variables

309

# might be reported in error state even when breakpoint is not in final

310

# state.

311

#

312

# The message may refer to variable name with `refers_to` set to

313

# `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.

314

# In either case variable value and members will be unset.

315

#

316

# Example of error message applied to name: `Invalid expression syntax`.

317

#

318

# Example of information message applied to value: `Not captured`.

319

#

320

# Examples of error message applied to value:

321

#

322

# * `Malformed string`,

323

# * `Field f not found in class C`

324

# * `Null pointer dereference`

325

# The message can indicate an error or informational status, and refer to

326

# specific parts of the containing object.

327

# For example, the `Breakpoint.status` field can indicate an error referring

328

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

329

"isError": True or False, # Distinguishes errors from informational messages.

330

"description": { # Represents a message with parameters. # Status message text.

331

"parameters": [ # Optional parameters to be embedded into the message.

332

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

333

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

334

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

335

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

340

# * `Failed to load '$0' which helps debug $1 the first time it

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

341

# is loaded. Again, $0 is very important.`

342

# * `Please pay $$10 to use $0 instead of $1.`

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

343

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

344

"refersTo": "A String", # Reference to which the message applies.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

345

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

346

"name": "A String", # Name of the variable, if any.

347

"type": "A String", # Variable type (e.g. `MyClass`). If the variable is split with

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

348

# `var_table_index`, `type` goes next to `value`. The interpretation of

349

# a type is agent specific. It is recommended to include the dynamic type

350

# rather than a static type of an object.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

351

"varTableIndex": 42, # Reference to a variable in the shared variable table. More than

352

# one variable can reference the same variable in the table. The

353

# `var_table_index` field is an index into `variable_table` in Breakpoint.

354

"value": "A String", # Simple value of the variable.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

355

},

356

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

357

"createTime": "A String", # Time this breakpoint was created by the server in seconds resolution.

358

"logMessageFormat": "A String", # Only relevant when action is `LOG`. Defines the message to log when

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

359

# the breakpoint hits. The message may include parameter placeholders `$0`,

360

# `$1`, etc. These placeholders are replaced with the evaluated value

361

# of the appropriate expression. Expressions not referenced in

362

# `log_message_format` are not logged.

363

#

364

# Example: `Message received, id = $0, count = $1` with

365

# `expressions` = `[ message.id, message.count ]`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

366

"labels": { # A set of custom breakpoint properties, populated by the agent, to be

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

367

# displayed to the user.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

368

"a_key": "A String",

Jon Wayne Parrott

0a471d3

2016-05-19 10:54:38 -0700

[diff] [blame]

369

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

370

"expressions": [ # List of read-only expressions to evaluate at the breakpoint location.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

371

# The expressions are composed using expressions in the programming language

372

# at the source location. If the breakpoint action is `LOG`, the evaluated

373

# expressions are included in log statements.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

374

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

375

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

376

"evaluatedExpressions": [ # Values of evaluated expressions at breakpoint time.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

377

# The evaluated expressions appear in exactly the same order they

378

# are listed in the `expressions` field.

379

# The `name` field holds the original expression text, the `value` or

380

# `members` field holds the result of the evaluated expression.

381

# If the expression cannot be evaluated, the `status` inside the `Variable`

382

# will indicate an error and contain the error text.

383

{ # Represents a variable or an argument possibly of a compound object type.

384

# Note how the following variables are represented:

385

#

386

# 1) A simple variable:

387

#

388

# int x = 5

389

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

390

# { name: "x", value: "5", type: "int" } // Captured variable

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

391

#

392

# 2) A compound object:

#

# struct T {

# int m1;

# int m2;

# };

# T x = { 3, 7 };

#

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

401

# name: "x",

402

# type: "T",

403

# members { name: "m1", value: "3", type: "int" },

404

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

405

# }

406

#

407

# 3) A pointer where the pointee was captured:

408

#

409

# T x = { 3, 7 };

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

410

# T* p = &x;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

411

#

412

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

413

# name: "p",

414

# type: "T*",

415

# value: "0x00500500",

416

# members { name: "m1", value: "3", type: "int" },

417

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

418

# }

419

#

420

# 4) A pointer where the pointee was not captured:

#

# T* p = new T;

#

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

425

# name: "p",

426

# type: "T*",

427

# value: "0x00400400"

428

# status { is_error: true, description { format: "unavailable" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

429

# }

430

#

431

# The status should describe the reason for the missing value,

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

432

# such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

433

#

434

# Note that a null pointer should not have members.

435

#

436

# 5) An unnamed value:

437

#

438

# int* p = new int(7);

439

#

440

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

441

# name: "p",

442

# value: "0x00500500",

443

# type: "int*",

444

# members { value: "7", type: "int" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

445

#

446

# 6) An unnamed pointer where the pointee was not captured:

447

#

448

# int* p = new int(7);

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

449

# int** pp = &p;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

450

#

451

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

452

# name: "pp",

453

# value: "0x00500500",

454

# type: "int**",

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

455

# members {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

456

# value: "0x00400400",

457

# type: "int*"

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

458

# status {

459

# is_error: true,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

460

# description: { format: "unavailable" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

# }

# }

# }

#

# To optimize computation, memory and network traffic, variables that

466

# repeat in the output multiple times can be stored once in a shared

467

# variable table and be referenced using the `var_table_index` field. The

468

# variables stored in the shared table are nameless and are essentially

469

# a partition of the complete variable. To reconstruct the complete

470

# variable, merge the referencing variable with the referenced variable.

471

#

472

# When using the shared variable table, the following variables:

473

#

474

# T x = { 3, 7 };

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

475

# T* p = &x;

476

# T& r = x;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

477

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

478

# { name: "x", var_table_index: 3, type: "T" } // Captured variables

479

# { name: "p", value "0x00500500", type="T*", var_table_index: 3 }

480

# { name: "r", type="T&", var_table_index: 3 }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

481

#

482

# { // Shared variable table entry #3:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

483

# members { name: "m1", value: "3", type: "int" },

484

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

485

# }

486

#

487

# Note that the pointer address is stored with the referencing variable

488

# and not with the referenced variable. This allows the referenced variable

489

# to be shared between pointers and references.

490

#

491

# The type field is optional. The debugger agent may or may not support it.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

492

"members": [ # Members contained or pointed to by the variable.

493

# Object with schema name: Variable

494

],

495

"status": { # Represents a contextual status message. # Status associated with the variable. This field will usually stay

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

496

# unset. A status of a single variable only applies to that variable or

497

# expression. The rest of breakpoint data still remains valid. Variables

498

# might be reported in error state even when breakpoint is not in final

499

# state.

500

#

501

# The message may refer to variable name with `refers_to` set to

502

# `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.

503

# In either case variable value and members will be unset.

504

#

505

# Example of error message applied to name: `Invalid expression syntax`.

506

#

507

# Example of information message applied to value: `Not captured`.

508

#

509

# Examples of error message applied to value:

510

#

511

# * `Malformed string`,

512

# * `Field f not found in class C`

513

# * `Null pointer dereference`

514

# The message can indicate an error or informational status, and refer to

515

# specific parts of the containing object.

516

# For example, the `Breakpoint.status` field can indicate an error referring

517

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

518

"isError": True or False, # Distinguishes errors from informational messages.

519

"description": { # Represents a message with parameters. # Status message text.

520

"parameters": [ # Optional parameters to be embedded into the message.

521

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

522

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

523

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

524

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

529

# * `Failed to load '$0' which helps debug $1 the first time it

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

530

# is loaded. Again, $0 is very important.`

531

# * `Please pay $$10 to use $0 instead of $1.`

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

532

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

533

"refersTo": "A String", # Reference to which the message applies.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

534

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

535

"name": "A String", # Name of the variable, if any.

536

"type": "A String", # Variable type (e.g. `MyClass`). If the variable is split with

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

537

# `var_table_index`, `type` goes next to `value`. The interpretation of

538

# a type is agent specific. It is recommended to include the dynamic type

539

# rather than a static type of an object.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

540

"varTableIndex": 42, # Reference to a variable in the shared variable table. More than

541

# one variable can reference the same variable in the table. The

542

# `var_table_index` field is an index into `variable_table` in Breakpoint.

543

"value": "A String", # Simple value of the variable.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

544

},

545

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

546

"isFinalState": True or False, # When true, indicates that this is a final result and the

547

# breakpoint state will not change from here on.

548

"stackFrames": [ # The stack at breakpoint time, where stack_frames[0] represents the most

549

# recently entered function.

550

{ # Represents a stack frame context.

551

"arguments": [ # Set of arguments passed to this function.

552

# Note that this might not be populated for all stack frames.

553

{ # Represents a variable or an argument possibly of a compound object type.

554

# Note how the following variables are represented:

555

#

556

# 1) A simple variable:

#

# int x = 5

#

# { name: "x", value: "5", type: "int" } // Captured variable

561

#

562

# 2) A compound object:

#

# struct T {

# int m1;

# int m2;

# };

# T x = { 3, 7 };

#

# { // Captured variable

571

# name: "x",

572

# type: "T",

573

# members { name: "m1", value: "3", type: "int" },

574

# members { name: "m2", value: "7", type: "int" }

575

# }

576

#

577

# 3) A pointer where the pointee was captured:

#

# T x = { 3, 7 };

# T* p = &x;

#

# { // Captured variable

583

# name: "p",

584

# type: "T*",

585

# value: "0x00500500",

586

# members { name: "m1", value: "3", type: "int" },

587

# members { name: "m2", value: "7", type: "int" }

588

# }

589

#

590

# 4) A pointer where the pointee was not captured:

#

# T* p = new T;

#

# { // Captured variable

595

# name: "p",

596

# type: "T*",

597

# value: "0x00400400"

598

# status { is_error: true, description { format: "unavailable" } }

599

# }

600

#

601

# The status should describe the reason for the missing value,

602

# such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.

603

#

604

# Note that a null pointer should not have members.

605

#

606

# 5) An unnamed value:

607

#

608

# int* p = new int(7);

609

#

610

# { // Captured variable

611

# name: "p",

612

# value: "0x00500500",

613

# type: "int*",

614

# members { value: "7", type: "int" } }

615

#

616

# 6) An unnamed pointer where the pointee was not captured:

617

#

618

# int* p = new int(7);

619

# int** pp = &p;

620

#

621

# { // Captured variable

622

# name: "pp",

623

# value: "0x00500500",

624

# type: "int**",

625

# members {

626

# value: "0x00400400",

# type: "int*"

# status {

# is_error: true,

# description: { format: "unavailable" } }

# }

# }

# }

#

# To optimize computation, memory and network traffic, variables that

636

# repeat in the output multiple times can be stored once in a shared

637

# variable table and be referenced using the `var_table_index` field. The

638

# variables stored in the shared table are nameless and are essentially

639

# a partition of the complete variable. To reconstruct the complete

640

# variable, merge the referencing variable with the referenced variable.

641

#

642

# When using the shared variable table, the following variables:

#

# T x = { 3, 7 };

# T* p = &x;

# T& r = x;

#

# { name: "x", var_table_index: 3, type: "T" } // Captured variables

649

# { name: "p", value "0x00500500", type="T*", var_table_index: 3 }

650

# { name: "r", type="T&", var_table_index: 3 }

651

#

652

# { // Shared variable table entry #3:

653

# members { name: "m1", value: "3", type: "int" },

654

# members { name: "m2", value: "7", type: "int" }

655

# }

656

#

657

# Note that the pointer address is stored with the referencing variable

658

# and not with the referenced variable. This allows the referenced variable

659

# to be shared between pointers and references.

660

#

661

# The type field is optional. The debugger agent may or may not support it.

662

"members": [ # Members contained or pointed to by the variable.

663

# Object with schema name: Variable

664

],

665

"status": { # Represents a contextual status message. # Status associated with the variable. This field will usually stay

666

# unset. A status of a single variable only applies to that variable or

667

# expression. The rest of breakpoint data still remains valid. Variables

668

# might be reported in error state even when breakpoint is not in final

669

# state.

670

#

671

# The message may refer to variable name with `refers_to` set to

672

# `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.

673

# In either case variable value and members will be unset.

674

#

675

# Example of error message applied to name: `Invalid expression syntax`.

676

#

677

# Example of information message applied to value: `Not captured`.

678

#

679

# Examples of error message applied to value:

680

#

681

# * `Malformed string`,

682

# * `Field f not found in class C`

683

# * `Null pointer dereference`

684

# The message can indicate an error or informational status, and refer to

685

# specific parts of the containing object.

686

# For example, the `Breakpoint.status` field can indicate an error referring

687

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

688

"isError": True or False, # Distinguishes errors from informational messages.

689

"description": { # Represents a message with parameters. # Status message text.

690

"parameters": [ # Optional parameters to be embedded into the message.

691

"A String",

692

],

693

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

694

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

# * `Failed to load '$0' which helps debug $1 the first time it

700

# is loaded. Again, $0 is very important.`

701

# * `Please pay $$10 to use $0 instead of $1.`

702

},

703

"refersTo": "A String", # Reference to which the message applies.

704

},

705

"name": "A String", # Name of the variable, if any.

706

"type": "A String", # Variable type (e.g. `MyClass`). If the variable is split with

707

# `var_table_index`, `type` goes next to `value`. The interpretation of

708

# a type is agent specific. It is recommended to include the dynamic type

709

# rather than a static type of an object.

710

"varTableIndex": 42, # Reference to a variable in the shared variable table. More than

711

# one variable can reference the same variable in the table. The

712

# `var_table_index` field is an index into `variable_table` in Breakpoint.

713

"value": "A String", # Simple value of the variable.

714

},

715

],

716

"locals": [ # Set of local variables at the stack frame location.

717

# Note that this might not be populated for all stack frames.

718

{ # Represents a variable or an argument possibly of a compound object type.

719

# Note how the following variables are represented:

720

#

721

# 1) A simple variable:

#

# int x = 5

#

# { name: "x", value: "5", type: "int" } // Captured variable

726

#

727

# 2) A compound object:

#

# struct T {

# int m1;

# int m2;

# };

# T x = { 3, 7 };

#

# { // Captured variable

736

# name: "x",

737

# type: "T",

738

# members { name: "m1", value: "3", type: "int" },

739

# members { name: "m2", value: "7", type: "int" }

740

# }

741

#

742

# 3) A pointer where the pointee was captured:

#

# T x = { 3, 7 };

# T* p = &x;

#

# { // Captured variable

748

# name: "p",

749

# type: "T*",

750

# value: "0x00500500",

751

# members { name: "m1", value: "3", type: "int" },

752

# members { name: "m2", value: "7", type: "int" }

753

# }

754

#

755

# 4) A pointer where the pointee was not captured:

#

# T* p = new T;

#

# { // Captured variable

760

# name: "p",

761

# type: "T*",

762

# value: "0x00400400"

763

# status { is_error: true, description { format: "unavailable" } }

764

# }

765

#

766

# The status should describe the reason for the missing value,

767

# such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.

768

#

769

# Note that a null pointer should not have members.

770

#

771

# 5) An unnamed value:

772

#

773

# int* p = new int(7);

774

#

775

# { // Captured variable

776

# name: "p",

777

# value: "0x00500500",

778

# type: "int*",

779

# members { value: "7", type: "int" } }

780

#

781

# 6) An unnamed pointer where the pointee was not captured:

782

#

783

# int* p = new int(7);

784

# int** pp = &p;

785

#

786

# { // Captured variable

787

# name: "pp",

788

# value: "0x00500500",

789

# type: "int**",

790

# members {

791

# value: "0x00400400",

# type: "int*"

# status {

# is_error: true,

# description: { format: "unavailable" } }

# }

# }

# }

#

# To optimize computation, memory and network traffic, variables that

801

# repeat in the output multiple times can be stored once in a shared

802

# variable table and be referenced using the `var_table_index` field. The

803

# variables stored in the shared table are nameless and are essentially

804

# a partition of the complete variable. To reconstruct the complete

805

# variable, merge the referencing variable with the referenced variable.

806

#

807

# When using the shared variable table, the following variables:

#

# T x = { 3, 7 };

# T* p = &x;

# T& r = x;

#

# { name: "x", var_table_index: 3, type: "T" } // Captured variables

814

# { name: "p", value "0x00500500", type="T*", var_table_index: 3 }

815

# { name: "r", type="T&", var_table_index: 3 }

816

#

817

# { // Shared variable table entry #3:

818

# members { name: "m1", value: "3", type: "int" },

819

# members { name: "m2", value: "7", type: "int" }

820

# }

821

#

822

# Note that the pointer address is stored with the referencing variable

823

# and not with the referenced variable. This allows the referenced variable

824

# to be shared between pointers and references.

825

#

826

# The type field is optional. The debugger agent may or may not support it.

827

"members": [ # Members contained or pointed to by the variable.

828

# Object with schema name: Variable

829

],

830

"status": { # Represents a contextual status message. # Status associated with the variable. This field will usually stay

831

# unset. A status of a single variable only applies to that variable or

832

# expression. The rest of breakpoint data still remains valid. Variables

833

# might be reported in error state even when breakpoint is not in final

834

# state.

835

#

836

# The message may refer to variable name with `refers_to` set to

837

# `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.

838

# In either case variable value and members will be unset.

839

#

840

# Example of error message applied to name: `Invalid expression syntax`.

841

#

842

# Example of information message applied to value: `Not captured`.

843

#

844

# Examples of error message applied to value:

845

#

846

# * `Malformed string`,

847

# * `Field f not found in class C`

848

# * `Null pointer dereference`

849

# The message can indicate an error or informational status, and refer to

850

# specific parts of the containing object.

851

# For example, the `Breakpoint.status` field can indicate an error referring

852

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

853

"isError": True or False, # Distinguishes errors from informational messages.

854

"description": { # Represents a message with parameters. # Status message text.

855

"parameters": [ # Optional parameters to be embedded into the message.

856

"A String",

857

],

858

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

859

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

# * `Failed to load '$0' which helps debug $1 the first time it

865

# is loaded. Again, $0 is very important.`

866

# * `Please pay $$10 to use $0 instead of $1.`

867

},

868

"refersTo": "A String", # Reference to which the message applies.

869

},

870

"name": "A String", # Name of the variable, if any.

871

"type": "A String", # Variable type (e.g. `MyClass`). If the variable is split with

872

# `var_table_index`, `type` goes next to `value`. The interpretation of

873

# a type is agent specific. It is recommended to include the dynamic type

874

# rather than a static type of an object.

875

"varTableIndex": 42, # Reference to a variable in the shared variable table. More than

876

# one variable can reference the same variable in the table. The

877

# `var_table_index` field is an index into `variable_table` in Breakpoint.

878

"value": "A String", # Simple value of the variable.

879

},

880

],

881

"location": { # Represents a location in the source code. # Source location of the call site.

882

"path": "A String", # Path to the source file within the source context of the target binary.

883

"column": 42, # Column within a line. The first column in a line as the value `1`.

884

# Agents that do not support setting breakpoints on specific columns ignore

885

# this field.

886

"line": 42, # Line inside the file. The first line in the file has the value `1`.

887

},

888

"function": "A String", # Demangled function name at the call site.

889

},

890

],

891

"condition": "A String", # Condition that triggers the breakpoint.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

892

# The condition is a compound boolean expression composed using expressions

893

# in a programming language at the source location.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

894

},

895

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

896

"waitExpired": True or False, # If set to `true`, indicates that there is no change to the

897

# list of active breakpoints and the server-selected timeout has expired.

898

# The `breakpoints` field would be empty and should be ignored.

899

"nextWaitToken": "A String", # A token that can be used in the next method call to block until

900

# the list of breakpoints changes.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

}</pre>

</div>

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

905

<code class="details" id="update">update(debuggeeId, id, body=None, x__xgafv=None)</code>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

906

<pre>Updates the breakpoint state or mutable fields.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

907

The entire Breakpoint message must be sent back to the controller service.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

908

909

Updates to active breakpoint fields are only allowed if the new value

910

does not change the breakpoint specification. Updates to the `location`,

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

911

`condition` and `expressions` fields should not alter the breakpoint

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

912

semantics. These may only make changes such as canonicalizing a value

913

or snapping the location to the correct line of code.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

914

915

Args:

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

916

debuggeeId: string, Required. Identifies the debuggee being debugged. (required)

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

917

id: string, Breakpoint identifier, unique in the scope of the debuggee. (required)

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

918

body: object, The request body.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

919

The object takes the form of:

920

Jon Wayne Parrott

36e41bc

2016-02-19 16:02:29 -0800

[diff] [blame]

921

{ # Request to update an active breakpoint.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

922

"breakpoint": { # ------------------------------------------------------------------------------ # Required. Updated breakpoint information.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

923

# The field `id` must be set.

924

# The agent must echo all Breakpoint specification fields in the update.

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

925

# ## Breakpoint (the resource)

926

#

927

# Represents the breakpoint specification, status and results.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

928

"canaryExpireTime": "A String", # The deadline for the breakpoint to stay in CANARY_ACTIVE state. The value

929

# is meaningless when the breakpoint is not in CANARY_ACTIVE state.

930

"status": { # Represents a contextual status message. # Breakpoint status.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

931

#

932

# The status includes an error flag and a human readable message.

933

# This field is usually unset. The message can be either

934

# informational or an error message. Regardless, clients should always

935

# display the text message back to the user.

936

#

937

# Error status indicates complete failure of the breakpoint.

938

#

939

# Example (non-final state): `Still loading symbols...`

940

#

941

# Examples (final state):

942

#

943

# * `Invalid line number` referring to location

944

# * `Field f not found in class C` referring to condition

945

# The message can indicate an error or informational status, and refer to

946

# specific parts of the containing object.

947

# For example, the `Breakpoint.status` field can indicate an error referring

948

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

949

"isError": True or False, # Distinguishes errors from informational messages.

950

"description": { # Represents a message with parameters. # Status message text.

951

"parameters": [ # Optional parameters to be embedded into the message.

952

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

953

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

954

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

955

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

960

# * `Failed to load '$0' which helps debug $1 the first time it

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

961

# is loaded. Again, $0 is very important.`

962

# * `Please pay $$10 to use $0 instead of $1.`

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

963

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

964

"refersTo": "A String", # Reference to which the message applies.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

965

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

966

"state": "A String", # The current state of the breakpoint.

967

"userEmail": "A String", # E-mail address of the user that created this breakpoint

968

"action": "A String", # Action that the agent should perform when the code at the

969

# breakpoint location is hit.

970

"logLevel": "A String", # Indicates the severity of the log. Only relevant when action is `LOG`.

971

"id": "A String", # Breakpoint identifier, unique in the scope of the debuggee.

972

"location": { # Represents a location in the source code. # Breakpoint source location.

973

"path": "A String", # Path to the source file within the source context of the target binary.

974

"column": 42, # Column within a line. The first column in a line as the value `1`.

975

# Agents that do not support setting breakpoints on specific columns ignore

976

# this field.

977

"line": 42, # Line inside the file. The first line in the file has the value `1`.

978

},

979

"finalTime": "A String", # Time this breakpoint was finalized as seen by the server in seconds

980

# resolution.

981

"variableTable": [ # The `variable_table` exists to aid with computation, memory and network

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

982

# traffic optimization. It enables storing a variable once and reference

983

# it from multiple variables, including variables stored in the

984

# `variable_table` itself.

985

# For example, the same `this` object, which may appear at many levels of

986

# the stack, can have all of its data stored once in this table. The

987

# stack frame variables then would hold only a reference to it.

988

#

989

# The variable `var_table_index` field is an index into this repeated field.

990

# The stored objects are nameless and get their name from the referencing

991

# variable. The effective variable is a merge of the referencing variable

992

# and the referenced variable.

993

{ # Represents a variable or an argument possibly of a compound object type.

994

# Note how the following variables are represented:

995

#

996

# 1) A simple variable:

997

#

998

# int x = 5

999

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1000

# { name: "x", value: "5", type: "int" } // Captured variable

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1001

#

1002

# 2) A compound object:

#

# struct T {

# int m1;

# int m2;

# };

# T x = { 3, 7 };

#

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1011

# name: "x",

1012

# type: "T",

1013

# members { name: "m1", value: "3", type: "int" },

1014

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1015

# }

1016

#

1017

# 3) A pointer where the pointee was captured:

1018

#

1019

# T x = { 3, 7 };

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1020

# T* p = &x;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1021

#

1022

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1023

# name: "p",

1024

# type: "T*",

1025

# value: "0x00500500",

1026

# members { name: "m1", value: "3", type: "int" },

1027

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1028

# }

1029

#

1030

# 4) A pointer where the pointee was not captured:

#

# T* p = new T;

#

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1035

# name: "p",

1036

# type: "T*",

1037

# value: "0x00400400"

1038

# status { is_error: true, description { format: "unavailable" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1039

# }

1040

#

1041

# The status should describe the reason for the missing value,

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1042

# such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1043

#

1044

# Note that a null pointer should not have members.

1045

#

1046

# 5) An unnamed value:

1047

#

1048

# int* p = new int(7);

1049

#

1050

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1051

# name: "p",

1052

# value: "0x00500500",

1053

# type: "int*",

1054

# members { value: "7", type: "int" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1055

#

1056

# 6) An unnamed pointer where the pointee was not captured:

1057

#

1058

# int* p = new int(7);

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1059

# int** pp = &p;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1060

#

1061

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1062

# name: "pp",

1063

# value: "0x00500500",

1064

# type: "int**",

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1065

# members {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1066

# value: "0x00400400",

1067

# type: "int*"

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1068

# status {

1069

# is_error: true,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1070

# description: { format: "unavailable" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

# }

# }

# }

#

# To optimize computation, memory and network traffic, variables that

1076

# repeat in the output multiple times can be stored once in a shared

1077

# variable table and be referenced using the `var_table_index` field. The

1078

# variables stored in the shared table are nameless and are essentially

1079

# a partition of the complete variable. To reconstruct the complete

1080

# variable, merge the referencing variable with the referenced variable.

1081

#

1082

# When using the shared variable table, the following variables:

1083

#

1084

# T x = { 3, 7 };

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1085

# T* p = &x;

1086

# T& r = x;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1087

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1088

# { name: "x", var_table_index: 3, type: "T" } // Captured variables

1089

# { name: "p", value "0x00500500", type="T*", var_table_index: 3 }

1090

# { name: "r", type="T&", var_table_index: 3 }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1091

#

1092

# { // Shared variable table entry #3:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1093

# members { name: "m1", value: "3", type: "int" },

1094

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1095

# }

1096

#

1097

# Note that the pointer address is stored with the referencing variable

1098

# and not with the referenced variable. This allows the referenced variable

1099

# to be shared between pointers and references.

1100

#

1101

# The type field is optional. The debugger agent may or may not support it.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1102

"members": [ # Members contained or pointed to by the variable.

1103

# Object with schema name: Variable

1104

],

1105

"status": { # Represents a contextual status message. # Status associated with the variable. This field will usually stay

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1106

# unset. A status of a single variable only applies to that variable or

1107

# expression. The rest of breakpoint data still remains valid. Variables

1108

# might be reported in error state even when breakpoint is not in final

1109

# state.

1110

#

1111

# The message may refer to variable name with `refers_to` set to

1112

# `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.

1113

# In either case variable value and members will be unset.

1114

#

1115

# Example of error message applied to name: `Invalid expression syntax`.

1116

#

1117

# Example of information message applied to value: `Not captured`.

1118

#

1119

# Examples of error message applied to value:

1120

#

1121

# * `Malformed string`,

1122

# * `Field f not found in class C`

1123

# * `Null pointer dereference`

1124

# The message can indicate an error or informational status, and refer to

1125

# specific parts of the containing object.

1126

# For example, the `Breakpoint.status` field can indicate an error referring

1127

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1128

"isError": True or False, # Distinguishes errors from informational messages.

1129

"description": { # Represents a message with parameters. # Status message text.

1130

"parameters": [ # Optional parameters to be embedded into the message.

1131

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1132

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1133

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1134

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1139

# * `Failed to load '$0' which helps debug $1 the first time it

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1140

# is loaded. Again, $0 is very important.`

1141

# * `Please pay $$10 to use $0 instead of $1.`

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1142

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1143

"refersTo": "A String", # Reference to which the message applies.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1144

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1145

"name": "A String", # Name of the variable, if any.

1146

"type": "A String", # Variable type (e.g. `MyClass`). If the variable is split with

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1147

# `var_table_index`, `type` goes next to `value`. The interpretation of

1148

# a type is agent specific. It is recommended to include the dynamic type

1149

# rather than a static type of an object.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1150

"varTableIndex": 42, # Reference to a variable in the shared variable table. More than

1151

# one variable can reference the same variable in the table. The

1152

# `var_table_index` field is an index into `variable_table` in Breakpoint.

1153

"value": "A String", # Simple value of the variable.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1154

},

1155

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1156

"createTime": "A String", # Time this breakpoint was created by the server in seconds resolution.

1157

"logMessageFormat": "A String", # Only relevant when action is `LOG`. Defines the message to log when

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1158

# the breakpoint hits. The message may include parameter placeholders `$0`,

1159

# `$1`, etc. These placeholders are replaced with the evaluated value

1160

# of the appropriate expression. Expressions not referenced in

1161

# `log_message_format` are not logged.

1162

#

1163

# Example: `Message received, id = $0, count = $1` with

1164

# `expressions` = `[ message.id, message.count ]`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1165

"labels": { # A set of custom breakpoint properties, populated by the agent, to be

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1166

# displayed to the user.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1167

"a_key": "A String",

Jon Wayne Parrott

0a471d3

2016-05-19 10:54:38 -0700

[diff] [blame]

1168

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1169

"expressions": [ # List of read-only expressions to evaluate at the breakpoint location.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1170

# The expressions are composed using expressions in the programming language

1171

# at the source location. If the breakpoint action is `LOG`, the evaluated

1172

# expressions are included in log statements.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1173

"A String",

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1174

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1175

"evaluatedExpressions": [ # Values of evaluated expressions at breakpoint time.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1176

# The evaluated expressions appear in exactly the same order they

1177

# are listed in the `expressions` field.

1178

# The `name` field holds the original expression text, the `value` or

1179

# `members` field holds the result of the evaluated expression.

1180

# If the expression cannot be evaluated, the `status` inside the `Variable`

1181

# will indicate an error and contain the error text.

1182

{ # Represents a variable or an argument possibly of a compound object type.

1183

# Note how the following variables are represented:

1184

#

1185

# 1) A simple variable:

1186

#

1187

# int x = 5

1188

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1189

# { name: "x", value: "5", type: "int" } // Captured variable

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1190

#

1191

# 2) A compound object:

#

# struct T {

# int m1;

# int m2;

# };

# T x = { 3, 7 };

#

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1200

# name: "x",

1201

# type: "T",

1202

# members { name: "m1", value: "3", type: "int" },

1203

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1204

# }

1205

#

1206

# 3) A pointer where the pointee was captured:

1207

#

1208

# T x = { 3, 7 };

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1209

# T* p = &x;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1210

#

1211

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1212

# name: "p",

1213

# type: "T*",

1214

# value: "0x00500500",

1215

# members { name: "m1", value: "3", type: "int" },

1216

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1217

# }

1218

#

1219

# 4) A pointer where the pointee was not captured:

#

# T* p = new T;

#

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1224

# name: "p",

1225

# type: "T*",

1226

# value: "0x00400400"

1227

# status { is_error: true, description { format: "unavailable" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1228

# }

1229

#

1230

# The status should describe the reason for the missing value,

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1231

# such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1232

#

1233

# Note that a null pointer should not have members.

1234

#

1235

# 5) An unnamed value:

1236

#

1237

# int* p = new int(7);

1238

#

1239

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1240

# name: "p",

1241

# value: "0x00500500",

1242

# type: "int*",

1243

# members { value: "7", type: "int" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1244

#

1245

# 6) An unnamed pointer where the pointee was not captured:

1246

#

1247

# int* p = new int(7);

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1248

# int** pp = &p;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1249

#

1250

# { // Captured variable

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1251

# name: "pp",

1252

# value: "0x00500500",

1253

# type: "int**",

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1254

# members {

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1255

# value: "0x00400400",

1256

# type: "int*"

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1257

# status {

1258

# is_error: true,

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1259

# description: { format: "unavailable" } }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

# }

# }

# }

#

# To optimize computation, memory and network traffic, variables that

1265

# repeat in the output multiple times can be stored once in a shared

1266

# variable table and be referenced using the `var_table_index` field. The

1267

# variables stored in the shared table are nameless and are essentially

1268

# a partition of the complete variable. To reconstruct the complete

1269

# variable, merge the referencing variable with the referenced variable.

1270

#

1271

# When using the shared variable table, the following variables:

1272

#

1273

# T x = { 3, 7 };

Dan O'Meara

2020-05-01 07:42:23 -0700

[diff] [blame]

1274

# T* p = &x;

1275

# T& r = x;

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1276

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1277

# { name: "x", var_table_index: 3, type: "T" } // Captured variables

1278

# { name: "p", value "0x00500500", type="T*", var_table_index: 3 }

1279

# { name: "r", type="T&", var_table_index: 3 }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1280

#

1281

# { // Shared variable table entry #3:

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1282

# members { name: "m1", value: "3", type: "int" },

1283

# members { name: "m2", value: "7", type: "int" }

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1284

# }

1285

#

1286

# Note that the pointer address is stored with the referencing variable

1287

# and not with the referenced variable. This allows the referenced variable

1288

# to be shared between pointers and references.

1289

#

1290

# The type field is optional. The debugger agent may or may not support it.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1291

"members": [ # Members contained or pointed to by the variable.

1292

# Object with schema name: Variable

1293

],

1294

"status": { # Represents a contextual status message. # Status associated with the variable. This field will usually stay

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1295

# unset. A status of a single variable only applies to that variable or

1296

# expression. The rest of breakpoint data still remains valid. Variables

1297

# might be reported in error state even when breakpoint is not in final

1298

# state.

1299

#

1300

# The message may refer to variable name with `refers_to` set to

1301

# `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.

1302

# In either case variable value and members will be unset.

1303

#

1304

# Example of error message applied to name: `Invalid expression syntax`.

1305

#

1306

# Example of information message applied to value: `Not captured`.

1307

#

1308

# Examples of error message applied to value:

1309

#

1310

# * `Malformed string`,

1311

# * `Field f not found in class C`

1312

# * `Null pointer dereference`

1313

# The message can indicate an error or informational status, and refer to

1314

# specific parts of the containing object.

1315

# For example, the `Breakpoint.status` field can indicate an error referring

1316

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1317

"isError": True or False, # Distinguishes errors from informational messages.

1318

"description": { # Represents a message with parameters. # Status message text.

1319

"parameters": [ # Optional parameters to be embedded into the message.

1320

"A String",

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1321

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1322

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1323

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1328

# * `Failed to load '$0' which helps debug $1 the first time it

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1329

# is loaded. Again, $0 is very important.`

1330

# * `Please pay $$10 to use $0 instead of $1.`

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1331

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1332

"refersTo": "A String", # Reference to which the message applies.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1333

},

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1334

"name": "A String", # Name of the variable, if any.

1335

"type": "A String", # Variable type (e.g. `MyClass`). If the variable is split with

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1336

# `var_table_index`, `type` goes next to `value`. The interpretation of

1337

# a type is agent specific. It is recommended to include the dynamic type

1338

# rather than a static type of an object.

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1339

"varTableIndex": 42, # Reference to a variable in the shared variable table. More than

1340

# one variable can reference the same variable in the table. The

1341

# `var_table_index` field is an index into `variable_table` in Breakpoint.

1342

"value": "A String", # Simple value of the variable.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1343

},

1344

],

Bu Sun Kim

2020-05-20 12:08:20 -0700

[diff] [blame]

1345

"isFinalState": True or False, # When true, indicates that this is a final result and the

1346

# breakpoint state will not change from here on.

1347

"stackFrames": [ # The stack at breakpoint time, where stack_frames[0] represents the most

1348

# recently entered function.

1349

{ # Represents a stack frame context.

1350

"arguments": [ # Set of arguments passed to this function.

1351

# Note that this might not be populated for all stack frames.

1352

{ # Represents a variable or an argument possibly of a compound object type.

1353

# Note how the following variables are represented:

1354

#

1355

# 1) A simple variable:

#

# int x = 5

#

# { name: "x", value: "5", type: "int" } // Captured variable

1360

#

1361

# 2) A compound object:

#

# struct T {

# int m1;

# int m2;

# };

# T x = { 3, 7 };

#

# { // Captured variable

1370

# name: "x",

1371

# type: "T",

1372

# members { name: "m1", value: "3", type: "int" },

1373

# members { name: "m2", value: "7", type: "int" }

1374

# }

1375

#

1376

# 3) A pointer where the pointee was captured:

#

# T x = { 3, 7 };

# T* p = &x;

#

# { // Captured variable

1382

# name: "p",

1383

# type: "T*",

1384

# value: "0x00500500",

1385

# members { name: "m1", value: "3", type: "int" },

1386

# members { name: "m2", value: "7", type: "int" }

1387

# }

1388

#

1389

# 4) A pointer where the pointee was not captured:

#

# T* p = new T;

#

# { // Captured variable

1394

# name: "p",

1395

# type: "T*",

1396

# value: "0x00400400"

1397

# status { is_error: true, description { format: "unavailable" } }

1398

# }

1399

#

1400

# The status should describe the reason for the missing value,

1401

# such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.

1402

#

1403

# Note that a null pointer should not have members.

1404

#

1405

# 5) An unnamed value:

1406

#

1407

# int* p = new int(7);

1408

#

1409

# { // Captured variable

1410

# name: "p",

1411

# value: "0x00500500",

1412

# type: "int*",

1413

# members { value: "7", type: "int" } }

1414

#

1415

# 6) An unnamed pointer where the pointee was not captured:

1416

#

1417

# int* p = new int(7);

1418

# int** pp = &p;

1419

#

1420

# { // Captured variable

1421

# name: "pp",

1422

# value: "0x00500500",

1423

# type: "int**",

1424

# members {

1425

# value: "0x00400400",

# type: "int*"

# status {

# is_error: true,

# description: { format: "unavailable" } }

# }

# }

# }

#

# To optimize computation, memory and network traffic, variables that

1435

# repeat in the output multiple times can be stored once in a shared

1436

# variable table and be referenced using the `var_table_index` field. The

1437

# variables stored in the shared table are nameless and are essentially

1438

# a partition of the complete variable. To reconstruct the complete

1439

# variable, merge the referencing variable with the referenced variable.

1440

#

1441

# When using the shared variable table, the following variables:

#

# T x = { 3, 7 };

# T* p = &x;

# T& r = x;

#

# { name: "x", var_table_index: 3, type: "T" } // Captured variables

1448

# { name: "p", value "0x00500500", type="T*", var_table_index: 3 }

1449

# { name: "r", type="T&", var_table_index: 3 }

1450

#

1451

# { // Shared variable table entry #3:

1452

# members { name: "m1", value: "3", type: "int" },

1453

# members { name: "m2", value: "7", type: "int" }

1454

# }

1455

#

1456

# Note that the pointer address is stored with the referencing variable

1457

# and not with the referenced variable. This allows the referenced variable

1458

# to be shared between pointers and references.

1459

#

1460

# The type field is optional. The debugger agent may or may not support it.

1461

"members": [ # Members contained or pointed to by the variable.

1462

# Object with schema name: Variable

1463

],

1464

"status": { # Represents a contextual status message. # Status associated with the variable. This field will usually stay

1465

# unset. A status of a single variable only applies to that variable or

1466

# expression. The rest of breakpoint data still remains valid. Variables

1467

# might be reported in error state even when breakpoint is not in final

1468

# state.

1469

#

1470

# The message may refer to variable name with `refers_to` set to

1471

# `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.

1472

# In either case variable value and members will be unset.

1473

#

1474

# Example of error message applied to name: `Invalid expression syntax`.

1475

#

1476

# Example of information message applied to value: `Not captured`.

1477

#

1478

# Examples of error message applied to value:

1479

#

1480

# * `Malformed string`,

1481

# * `Field f not found in class C`

1482

# * `Null pointer dereference`

1483

# The message can indicate an error or informational status, and refer to

1484

# specific parts of the containing object.

1485

# For example, the `Breakpoint.status` field can indicate an error referring

1486

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

1487

"isError": True or False, # Distinguishes errors from informational messages.

1488

"description": { # Represents a message with parameters. # Status message text.

1489

"parameters": [ # Optional parameters to be embedded into the message.

1490

"A String",

1491

],

1492

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

1493

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

# * `Failed to load '$0' which helps debug $1 the first time it

1499

# is loaded. Again, $0 is very important.`

1500

# * `Please pay $$10 to use $0 instead of $1.`

1501

},

1502

"refersTo": "A String", # Reference to which the message applies.

1503

},

1504

"name": "A String", # Name of the variable, if any.

1505

"type": "A String", # Variable type (e.g. `MyClass`). If the variable is split with

1506

# `var_table_index`, `type` goes next to `value`. The interpretation of

1507

# a type is agent specific. It is recommended to include the dynamic type

1508

# rather than a static type of an object.

1509

"varTableIndex": 42, # Reference to a variable in the shared variable table. More than

1510

# one variable can reference the same variable in the table. The

1511

# `var_table_index` field is an index into `variable_table` in Breakpoint.

1512

"value": "A String", # Simple value of the variable.

1513

},

1514

],

1515

"locals": [ # Set of local variables at the stack frame location.

1516

# Note that this might not be populated for all stack frames.

1517

{ # Represents a variable or an argument possibly of a compound object type.

1518

# Note how the following variables are represented:

1519

#

1520

# 1) A simple variable:

#

# int x = 5

#

# { name: "x", value: "5", type: "int" } // Captured variable

1525

#

1526

# 2) A compound object:

#

# struct T {

# int m1;

# int m2;

# };

# T x = { 3, 7 };

#

# { // Captured variable

1535

# name: "x",

1536

# type: "T",

1537

# members { name: "m1", value: "3", type: "int" },

1538

# members { name: "m2", value: "7", type: "int" }

1539

# }

1540

#

1541

# 3) A pointer where the pointee was captured:

#

# T x = { 3, 7 };

# T* p = &x;

#

# { // Captured variable

1547

# name: "p",

1548

# type: "T*",

1549

# value: "0x00500500",

1550

# members { name: "m1", value: "3", type: "int" },

1551

# members { name: "m2", value: "7", type: "int" }

1552

# }

1553

#

1554

# 4) A pointer where the pointee was not captured:

#

# T* p = new T;

#

# { // Captured variable

1559

# name: "p",

1560

# type: "T*",

1561

# value: "0x00400400"

1562

# status { is_error: true, description { format: "unavailable" } }

1563

# }

1564

#

1565

# The status should describe the reason for the missing value,

1566

# such as `<optimized out>`, `<inaccessible>`, `<pointers limit reached>`.

1567

#

1568

# Note that a null pointer should not have members.

1569

#

1570

# 5) An unnamed value:

1571

#

1572

# int* p = new int(7);

1573

#

1574

# { // Captured variable

1575

# name: "p",

1576

# value: "0x00500500",

1577

# type: "int*",

1578

# members { value: "7", type: "int" } }

1579

#

1580

# 6) An unnamed pointer where the pointee was not captured:

1581

#

1582

# int* p = new int(7);

1583

# int** pp = &p;

1584

#

1585

# { // Captured variable

1586

# name: "pp",

1587

# value: "0x00500500",

1588

# type: "int**",

1589

# members {

1590

# value: "0x00400400",

# type: "int*"

# status {

# is_error: true,

# description: { format: "unavailable" } }

# }

# }

# }

#

# To optimize computation, memory and network traffic, variables that

1600

# repeat in the output multiple times can be stored once in a shared

1601

# variable table and be referenced using the `var_table_index` field. The

1602

# variables stored in the shared table are nameless and are essentially

1603

# a partition of the complete variable. To reconstruct the complete

1604

# variable, merge the referencing variable with the referenced variable.

1605

#

1606

# When using the shared variable table, the following variables:

#

# T x = { 3, 7 };

# T* p = &x;

# T& r = x;

#

# { name: "x", var_table_index: 3, type: "T" } // Captured variables

1613

# { name: "p", value "0x00500500", type="T*", var_table_index: 3 }

1614

# { name: "r", type="T&", var_table_index: 3 }

1615

#

1616

# { // Shared variable table entry #3:

1617

# members { name: "m1", value: "3", type: "int" },

1618

# members { name: "m2", value: "7", type: "int" }

1619

# }

1620

#

1621

# Note that the pointer address is stored with the referencing variable

1622

# and not with the referenced variable. This allows the referenced variable

1623

# to be shared between pointers and references.

1624

#

1625

# The type field is optional. The debugger agent may or may not support it.

1626

"members": [ # Members contained or pointed to by the variable.

1627

# Object with schema name: Variable

1628

],

1629

"status": { # Represents a contextual status message. # Status associated with the variable. This field will usually stay

1630

# unset. A status of a single variable only applies to that variable or

1631

# expression. The rest of breakpoint data still remains valid. Variables

1632

# might be reported in error state even when breakpoint is not in final

1633

# state.

1634

#

1635

# The message may refer to variable name with `refers_to` set to

1636

# `VARIABLE_NAME`. Alternatively `refers_to` will be set to `VARIABLE_VALUE`.

1637

# In either case variable value and members will be unset.

1638

#

1639

# Example of error message applied to name: `Invalid expression syntax`.

1640

#

1641

# Example of information message applied to value: `Not captured`.

1642

#

1643

# Examples of error message applied to value:

1644

#

1645

# * `Malformed string`,

1646

# * `Field f not found in class C`

1647

# * `Null pointer dereference`

1648

# The message can indicate an error or informational status, and refer to

1649

# specific parts of the containing object.

1650

# For example, the `Breakpoint.status` field can indicate an error referring

1651

# to the `BREAKPOINT_SOURCE_LOCATION` with the message `Location not found`.

1652

"isError": True or False, # Distinguishes errors from informational messages.

1653

"description": { # Represents a message with parameters. # Status message text.

1654

"parameters": [ # Optional parameters to be embedded into the message.

1655

"A String",

1656

],

1657

"format": "A String", # Format template for the message. The `format` uses placeholders `$0`,

1658

# `$1`, etc. to reference parameters. `$$` can be used to denote the `$`

# character.

#

# Examples:

#

# * `Failed to load '$0' which helps debug $1 the first time it

1664

# is loaded. Again, $0 is very important.`

1665

# * `Please pay $$10 to use $0 instead of $1.`

1666

},

1667

"refersTo": "A String", # Reference to which the message applies.

1668

},

1669

"name": "A String", # Name of the variable, if any.

1670

"type": "A String", # Variable type (e.g. `MyClass`). If the variable is split with

1671

# `var_table_index`, `type` goes next to `value`. The interpretation of

1672

# a type is agent specific. It is recommended to include the dynamic type

1673

# rather than a static type of an object.

1674

"varTableIndex": 42, # Reference to a variable in the shared variable table. More than

1675

# one variable can reference the same variable in the table. The

1676

# `var_table_index` field is an index into `variable_table` in Breakpoint.

1677

"value": "A String", # Simple value of the variable.

1678

},

1679

],

1680

"location": { # Represents a location in the source code. # Source location of the call site.

1681

"path": "A String", # Path to the source file within the source context of the target binary.

1682

"column": 42, # Column within a line. The first column in a line as the value `1`.

1683

# Agents that do not support setting breakpoints on specific columns ignore

1684

# this field.

1685

"line": 42, # Line inside the file. The first line in the file has the value `1`.

1686

},

1687

"function": "A String", # Demangled function name at the call site.

1688

},

1689

],

1690

"condition": "A String", # Condition that triggers the breakpoint.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1691

# The condition is a compound boolean expression composed using expressions

1692

# in a programming language at the source location.

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

},

}

x__xgafv: string, V1 error format.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1697

Allowed values

1698

1 - v1 error format

1699

2 - v2 error format

Takashi Matsuo

2015-09-11 13:55:40 -0700

[diff] [blame]

1700

1701

Returns:

1702

An object of the form:

1703

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1704

{ # Response for updating an active breakpoint.

1705

# The message is defined to allow future extensions.

Takashi Matsuo