~ntt-pf-lab/nova/monkey_patch_notification

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Twisted Documentation: Using Perspective Broker</title>

</head>

<h1 class="title">Using Perspective Broker</h1>

<div class="toc"><ol><li><a href="#auto0">Basic Example</a></li><li><a href="#auto1">Complete Example</a></li><li><a href="#auto2">References can come back to you</a></li><li><a href="#auto3">References to client-side objects</a></li><li><a href="#auto4">Raising Remote Exceptions</a></li><li><a href="#auto5">Try/Except blocks and Failure.trap </a></li></ol></div>

<h2>Basic Example<a name="auto0"/></h2>

The first example to look at is a complete (although somewhat trivial)

application. It uses <code>PBServerFactory()</code> on the server side, and

<code>PBClientFactory()</code> on the client side.

<div class="py-listing"><pre> 1

from twisted.spread import pb

from twisted.internet import reactor

class Echoer(pb.Root):

def remote_echo(self, st):

print 'echoing:', st

return st

if __name__ == '__main__':

reactor.listenTCP(8789, pb.PBServerFactory(Echoer()))

reactor.run()

</pre><div class="caption">Source listing - <a href="../examples/pbsimple.py">../examples/pbsimple.py</a></div></div>

<div class="py-listing"><pre> 1

from twisted.python import util

factory = pb.PBClientFactory()

reactor.connectTCP("localhost", 8789, factory)

d = factory.getRootObject()

d.addCallback(lambda object: object.callRemote("echo", "hello network"))

d.addCallback(lambda echo: 'server echoed: '+echo)

d.addErrback(lambda reason: 'error: '+str(reason.value))

d.addCallback(util.println)

d.addCallback(lambda _: reactor.stop())

reactor.run()

</pre><div class="caption">Source listing - <a href="../examples/pbsimpleclient.py">../examples/pbsimpleclient.py</a></div></div>

First we look at the server. This defines an Echoer class (derived from

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code>), with a method called

<code>remote_echo()</code>.

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code> objects (because of

their inheritance of

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">pb.Referenceable</a></code>, described

later) can define methods with names of the form <code>remote_*</code>; a

client which obtains a remote reference to that

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code> object will be able to

invoke those methods.

The <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code>-ish object is

given to a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.PBServerFactory.html" title="twisted.spread.pb.PBServerFactory">pb.PBServerFactory</a></code><code>()</code>. This is a

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.protocol.Factory.html" title="twisted.internet.protocol.Factory">Factory</a></code> object like

any other: the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.protocol.Protocol.html" title="twisted.internet.protocol.Protocol">Protocol</a></code> objects it creates for new

connections know how to speak the PB protocol. The object you give to

<code>pb.PBServerFactory()</code> becomes the <q>root object</q>, which

simply makes it available for the client to retrieve. The client may only

request references to the objects you want to provide it: this helps you

implement your security model. Because it is so common to export just a

single object (and because a <code>remote_*</code> method on that one can

return a reference to any other object you might want to give out), the

simplest example is one where the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.PBServerFactory.html" title="twisted.spread.pb.PBServerFactory">PBServerFactory</a></code> is given the root object, and

the client retrieves it.

The client side uses

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.PBClientFactory.html" title="twisted.spread.pb.PBClientFactory">pb.PBClientFactory</a></code> to make a

connection to a given port. This is a two-step process involving opening

a TCP connection to a given host and port and requesting the root object

using <code>.getRootObject()</code>.

100

101

Because <code>.getRootObject()</code> has to wait until a network

102

connection has been made and exchange some data, it may take a while,

103

so it returns a Deferred, to which the gotObject() callback is

104

attached. (See the documentation on <a href="defer.html" shape="rect">Deferring

105

Execution</a> for a complete explanation of <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code>s). If and when the

106

connection succeeds and a reference to the remote root object is

107

obtained, this callback is run. The first argument passed to the

108

callback is a remote reference to the distant root object. (you can

109

give other arguments to the callback too, see the other parameters for

110

<code>.addCallback()</code> and <code>.addCallbacks()</code>).

111

112

The callback does:

113

114

<pre class="python">1

115

object.callRemote("echo", "hello network")

116

</pre>

117

118

which causes the server's <code>.remote_echo()</code> method to be invoked.

119

(running <code>.callRemote("boom")</code> would cause

120

<code>.remote_boom()</code> to be run, etc). Again because of the delay

121

involved, <code>callRemote()</code> returns a

122

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code>. Assuming the

123

remote method was run without causing an exception (including an attempt to

124

invoke an unknown method), the callback attached to that

125

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code> will be

126

invoked with any objects that were returned by the remote method call.

127

128

In this example, the server's <code>Echoer</code> object has a method

129

invoked, exactly as if some code on the server side had done:

130

131

<pre class="python">1

132

echoer_object.remote_echo("hello network")

133

</pre>

134

135

and from the definition of <code>remote_echo()</code> we see that this just

136

returns the same string it was given: <q>hello network</q>.

137

138

From the client's point of view, the remote call gets another <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code> object instead of

139

that string. <code>callRemote()</code> always returns a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code>. This is why PB is

140

described as a system for <q>translucent</q> remote method calls instead of

141

<q>transparent</q> ones: you cannot pretend that the remote object is really

142

local. Trying to do so (as some other RPC mechanisms do, coughCORBAcough)

143

breaks down when faced with the asynchronous nature of the network. Using

144

Deferreds turns out to be a very clean way to deal with the whole thing.

145

146

The remote reference object (the one given to

147

<code>getRootObject()</code>'s success callback) is an instance the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.RemoteReference.html" title="twisted.spread.pb.RemoteReference">RemoteReference</a></code> class. This means

148

you can use it to invoke methods on the remote object that it refers to. Only

149

instances of <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.RemoteReference.html" title="twisted.spread.pb.RemoteReference">RemoteReference</a></code> are eligible for

150

<code>.callRemote()</code>. The <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.RemoteReference.html" title="twisted.spread.pb.RemoteReference">RemoteReference</a></code> object is the one that lives

151

on the remote side (the client, in this case), not the local side (where the

152

actual object is defined).

153

154

In our example, the local object is that <code>Echoer()</code> instance,

155

which inherits from <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code>,

156

which inherits from

157

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">pb.Referenceable</a></code>. It is that

158

<code>Referenceable</code> class that makes the object eligible to be available

159

for remote method calls<a href="#footnote-1" title="There are a few other classes that can bestow this ability, but pb.Referenceable is the easiest to understand; see 'flavors' below for details on the others."><super>1</super></a>. If you have

160

an object that is Referenceable, then any client that manages to get a

161

reference to it can invoke any <code>remote_*</code> methods they please.

162

163

<div class="note">Note:

164

The only thing they can do is invoke those

165

methods. In particular, they cannot access attributes. From a security point

166

of view, you control what they can do by limiting what the

167

<code>remote_*</code> methods can do.

168

169

Also note: the other classes like

170

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">Referenceable</a></code> allow access to

171

other methods, in particular <code>perspective_*</code> and <code>view_*</code>

172

may be accessed. Don't write local-only methods with these names, because then

173

remote callers will be able to do more than you intended.

174

175

Also also note: the other classes like

176

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code> do allow

177

access to attributes, but you control which ones they can see.

178

</div>

179

180

You don't have to be a

181

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code> to be remotely callable,

182

but you do have to be

183

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">pb.Referenceable</a></code>. (Objects that

184

inherit from <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">pb.Referenceable</a></code>

185

but not from <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code> can be

186

remotely called, but only

187

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code>-ish objects can be given

188

to the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.PBServerFactory.html" title="twisted.spread.pb.PBServerFactory">PBServerFactory</a></code>.)

189

190

<h2>Complete Example<a name="auto1"/></h2>

191

192

Here is an example client and server which uses <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">pb.Referenceable</a></code> as a root object and as the

193

result of a remotely exposed method. In each context, methods can be invoked

194

on the exposed <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.Referenceable.html" title="twisted.spread.Referenceable">Referenceable</a></code>

195

instance. In this example, the initial root object has a method that returns a

196

reference to the second object.

197

198

<div class="py-listing"><pre> 1

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

#!/usr/bin/env python

219

220

221

# See LICENSE for details.

222

223

from twisted.spread import pb

224

225

class Two(pb.Referenceable):

226

def remote_three(self, arg):

227

print "Two.three was given", arg

228

229

class One(pb.Root):

230

def remote_getTwo(self):

231

two = Two()

232

print "returning a Two called", two

233

return two

234

235

236

reactor.listenTCP(8800, pb.PBServerFactory(One()))

237

reactor.run()

238

</pre><div class="caption">Source listing - <a href="listings/pb/pb1server.py">listings/pb/pb1server.py</a></div></div>

239

<div class="py-listing"><pre> 1

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

#!/usr/bin/env python

271

272

273

# See LICENSE for details.

274

275

276

277

278

def main():

279

factory = pb.PBClientFactory()

280

reactor.connectTCP("localhost", 8800, factory)

281

def1 = factory.getRootObject()

282

def1.addCallbacks(got_obj1, err_obj1)

283

reactor.run()

284

285

def err_obj1(reason):

286

print "error getting first object", reason

287

reactor.stop()

288

289

def got_obj1(obj1):

290

print "got first object:", obj1

291

print "asking it to getTwo"

292

def2 = obj1.callRemote("getTwo")

293

def2.addCallbacks(got_obj2)

294

295

def got_obj2(obj2):

296

print "got second object:", obj2

297

print "telling it to do three(12)"

298

obj2.callRemote("three", 12)

299

300

main()

301

</pre><div class="caption">Source listing - <a href="listings/pb/pb1client.py">listings/pb/pb1client.py</a></div></div>

302

303

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.PBClientFactory.getRootObject.html" title="twisted.spread.pb.PBClientFactory.getRootObject">pb.PBClientFactory.getRootObject</a></code> will

304

handle all the details of waiting for the creation of a connection.

305

It returns a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code>, which will have its

306

callback called when the reactor connects to the remote server and

307

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.PBClientFactory.html" title="twisted.spread.pb.PBClientFactory">pb.PBClientFactory</a></code> gets the

308

root, and have its <code class="python">errback</code> called when the

309

object-connection fails for any reason, whether it was host lookup

310

failure, connection refusal, or some server-side error.

311

312

313

The root object has a method called <code>remote_getTwo</code>, which

314

returns the <code>Two()</code> instance. On the client end, the callback gets

315

a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.RemoteReference.html" title="twisted.spread.pb.RemoteReference">RemoteReference</a></code> to that

316

instance. The client can then invoke two's <code>.remote_three()</code>

317

method.

318

319

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.RemoteReference.html" title="twisted.spread.pb.RemoteReference">RemoteReference</a></code>

320

objects have one method which is their purpose for being: <code class="python">callRemote</code>. This method allows you to call a

321

remote method on the object being referred to by the Reference. <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.RemoteReference.callRemote.html" title="twisted.spread.pb.RemoteReference.callRemote">RemoteReference.callRemote</a></code>, like <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.PBClientFactory.getRootObject.html" title="twisted.spread.pb.PBClientFactory.getRootObject">pb.PBClientFactory.getRootObject</a></code>, returns

322

a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code>.

323

When a response to the method-call being sent arrives, the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code>'s <code class="python">callback</code> or <code class="python">errback</code>

324

will be made, depending on whether an error occurred in processing the

325

method call.

326

327

You can use this technique to provide access to arbitrary sets of objects.

328

Just remember that any object that might get passed <q>over the wire</q> must

329

inherit from <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">Referenceable</a></code>

330

(or one of the other flavors). If you try to pass a non-Referenceable object

331

(say, by returning one from a <code>remote_*</code> method), you'll get an

332

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.jelly.InsecureJelly.html" title="twisted.spread.jelly.InsecureJelly">InsecureJelly</a></code>

333

exception<a href="#footnote-2" title="This can be overridden, by subclassing one of the Serializable flavors and defining custom serialization code for your class. See Passing Complex Types for details."><super>2</super></a>.

334

335

336

<h2>References can come back to you<a name="auto2"/></h2>

337

338

If your server gives a reference to a client, and then that client gives

339

the reference back to the server, the server will wind up with the same

340

object it gave out originally. The serialization layer watches for returning

341

reference identifiers and turns them into actual objects. You need to stay

342

aware of where the object lives: if it is on your side, you do actual method

343

calls. If it is on the other side, you do

344

<code>.callRemote()</code><a href="#footnote-3" title="The binary nature of this local vs. remote scheme works because you cannot give RemoteReferences to a third party. If you could, then your object A could go to B, B could give it to C, C might give it back to you, and you would be hard pressed to tell if the object lived in C's memory space, in B's, or if it was really your own object, tarnished and sullied after being handed down like a really ugly picture that your great aunt owned and which nobody wants but which nobody can bear to throw out. Ok, not really like that, but you get the idea."><super>3</super></a>.

345

346

<div class="py-listing"><pre> 1

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

#!/usr/bin/env python

377

378

379

# See LICENSE for details.

380

381

382

383

384

class Two(pb.Referenceable):

385

def remote_print(self, arg):

386

print "two.print was given", arg

387

388

class One(pb.Root):

389

def __init__(self, two):

390

#pb.Root.__init__(self) # pb.Root doesn't implement __init__

391

self.two = two

392

def remote_getTwo(self):

393

print "One.getTwo(), returning my two called", two

394

return two

395

def remote_checkTwo(self, newtwo):

396

print "One.checkTwo(): comparing my two", self.two

397

print "One.checkTwo(): against your two", newtwo

398

if two == newtwo:

399

print "One.checkTwo(): our twos are the same"

400

401

402

two = Two()

403

root_obj = One(two)

404

405

reactor.run()

406

</pre><div class="caption">Source listing - <a href="listings/pb/pb2server.py">listings/pb/pb2server.py</a></div></div>

407

<div class="py-listing"><pre> 1

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

#!/usr/bin/env python

444

445

446

# See LICENSE for details.

447

448

449

450

451

def main():

452

foo = Foo()

453

factory = pb.PBClientFactory()

454

reactor.connectTCP("localhost", 8800, factory)

455

factory.getRootObject().addCallback(foo.step1)

456

reactor.run()

457

458

# keeping globals around is starting to get ugly, so we use a simple class

459

# instead. Instead of hooking one function to the next, we hook one method

460

# to the next.

461

462

class Foo:

463

def __init__(self):

464

self.oneRef = None

465

466

def step1(self, obj):

467

print "got one object:", obj

468

self.oneRef = obj

469

print "asking it to getTwo"

470

self.oneRef.callRemote("getTwo").addCallback(self.step2)

471

472

def step2(self, two):

473

print "got two object:", two

474

print "giving it back to one"

475

print "one is", self.oneRef

476

self.oneRef.callRemote("checkTwo", two)

477

478

main()

479

</pre><div class="caption">Source listing - <a href="listings/pb/pb2client.py">listings/pb/pb2client.py</a></div></div>

480

481

The server gives a <code>Two()</code> instance to the client, who then

482

returns the reference back to the server. The server compares the <q>two</q>

483

given with the <q>two</q> received and shows that they are the same, and that

484

both are real objects instead of remote references.

485

486

A few other techniques are demonstrated in <code>pb2client.py</code>. One

487

is that the callbacks are are added with <code>.addCallback</code> instead

488

of <code>.addCallbacks</code>. As you can tell from the <a href="defer.html" shape="rect">Deferred</a> documentation, <code>.addCallback</code> is a

489

simplified form which only adds a success callback. The other is that to

490

keep track of state from one callback to the next (the remote reference to

491

the main One() object), we create a simple class, store the reference in an

492

instance thereof, and point the callbacks at a sequence of bound methods.

493

This is a convenient way to encapsulate a state machine. Each response kicks

494

off the next method, and any data that needs to be carried from one state to

495

the next can simply be saved as an attribute of the object.

496

497

Remember that the client can give you back any remote reference you've

498

given them. Don't base your zillion-dollar stock-trading clearinghouse

499

server on the idea that you trust the client to give you back the right

500

reference. The security model inherent in PB means that they can only

501

give you back a reference that you've given them for the current connection

502

(not one you've given to someone else instead, nor one you gave them last

503

time before the TCP session went down, nor one you haven't yet given to the

504

client), but just like with URLs and HTTP cookies, the particular reference

505

they give you is entirely under their control.

506

507

508

<h2>References to client-side objects<a name="auto3"/></h2>

509

510

Anything that's Referenceable can get passed across the wire, in

511

either direction. The <q>client</q> can give a reference to the

512

<q>server</q>, and then the server can use .callRemote() to invoke methods on

513

the client end. This fuzzes the distinction between <q>client</q> and

514

<q>server</q>: the only real difference is who initiates the original TCP

515

connection; after that it's all symmetric.

516

517

<div class="py-listing"><pre> 1

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

#!/usr/bin/env python

534

535

536

# See LICENSE for details.

537

538

539

540

541

class One(pb.Root):

542

def remote_takeTwo(self, two):

543

print "received a Two called", two

544

print "telling it to print(12)"

545

two.callRemote("print", 12)

546

547

548

reactor.run()

549

</pre><div class="caption">Source listing - <a href="listings/pb/pb3server.py">listings/pb/pb3server.py</a></div></div>

550

<div class="py-listing"><pre> 1

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

#!/usr/bin/env python

577

578

579

# See LICENSE for details.

580

581

582

583

584

class Two(pb.Referenceable):

585

def remote_print(self, arg):

586

print "Two.print() called with", arg

587

588

def main():

589

two = Two()

590

factory = pb.PBClientFactory()

591

reactor.connectTCP("localhost", 8800, factory)

592

def1 = factory.getRootObject()

593

def1.addCallback(got_obj, two) # hands our 'two' to the callback

594

reactor.run()

595

596

def got_obj(obj, two):

597

print "got One:", obj

598

print "giving it our two"

599

obj.callRemote("takeTwo", two)

600

601

main()

602

</pre><div class="caption">Source listing - <a href="listings/pb/pb3client.py">listings/pb/pb3client.py</a></div></div>

603

604

In this example, the client gives a reference to its own object to the

605

server. The server then invokes a remote method on the client-side

606

object.

607

608

609

<h2>Raising Remote Exceptions<a name="auto4"/></h2>

610

611

Everything so far has covered what happens when things go right. What

612

about when they go wrong? The Python Way is to raise an exception of some

613

sort. The Twisted Way is the same.

614

615

The only special thing you do is to define your <code>Exception</code>

616

subclass by deriving it from <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Error.html" title="twisted.spread.pb.Error">pb.Error</a></code>. When any remotely-invokable method

617

(like <code>remote_*</code> or <code>perspective_*</code>) raises a

618

<code>pb.Error</code>-derived exception, a serialized form of that Exception

619

object will be sent back over the wire<a href="#footnote-4" title="To be precise, the Failure will be sent if any exception is raised, not just pb.Error-derived ones. But the server will print ugly error messages if you raise ones that aren't derived from pb.Error."><super>4</super></a>. The other side (which

620

did <code>callRemote</code>) will have the <q><code>errback</code></q>

621

callback run with a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">Failure</a></code> object that contains a copy of

622

the exception object. This <code>Failure</code> object can be queried to

623

retrieve the error message and a stack traceback.

624

625

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">Failure</a></code> is a

626

special class, defined in <code>twisted/python/failure.py</code>, created to

627

make it easier to handle asynchronous exceptions. Just as exception handlers

628

can be nested, <code>errback</code> functions can be chained. If one errback

629

can't handle the particular type of failure, it can be <q>passed along</q> to a

630

errback handler further down the chain.

631

632

For simple purposes, think of the <code>Failure</code> as just a container

633

for remotely-thrown <code>Exception</code> objects. To extract the string that

634

was put into the exception, use its <code>.getErrorMessage()</code> method.

635

To get the type of the exception (as a string), look at its

636

<code>.type</code> attribute. The stack traceback is available too. The

637

intent is to let the errback function get just as much information about the

638

exception as Python's normal <code>try:</code> clauses do, even though the

639

exception occurred in somebody else's memory space at some unknown time in

640

the past.

641

642

<div class="py-listing"><pre> 1

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

#!/usr/bin/env python

675

676

677

# See LICENSE for details.

678

679

680

681

682

class MyError(pb.Error):

683

"""This is an Expected Exception. Something bad happened."""

684

pass

685

686

class MyError2(Exception):

687

"""This is an Unexpected Exception. Something really bad happened."""

688

pass

689

690

class One(pb.Root):

691

def remote_broken(self):

692

msg = "fall down go boom"

693

print "raising a MyError exception with data '%s'" % msg

694

raise MyError(msg)

695

def remote_broken2(self):

696

msg = "hadda owie"

697

print "raising a MyError2 exception with data '%s'" % msg

698

raise MyError2(msg)

699

700

def main():

701

702

reactor.run()

703

704

if __name__ == '__main__':

705

main()

706

</pre><div class="caption">Source listing - <a href="listings/pb/exc_server.py">listings/pb/exc_server.py</a></div></div>

707

<div class="py-listing"><pre> 1

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

#!/usr/bin/env python

741

742

743

# See LICENSE for details.

744

745

746

747

748

def main():

749

factory = pb.PBClientFactory()

750

reactor.connectTCP("localhost", 8800, factory)

751

d = factory.getRootObject()

752

d.addCallbacks(got_obj)

753

reactor.run()

754

755

def got_obj(obj):

756

# change "broken" into "broken2" to demonstrate an unhandled exception

757

d2 = obj.callRemote("broken")

758

d2.addCallback(working)

759

d2.addErrback(broken)

760

761

def working():

762

print "erm, it wasn't *supposed* to work.."

763

764

def broken(reason):

765

print "got remote Exception"

766

# reason should be a Failure (or subclass) holding the MyError exception

767

print " .__class__ =", reason.__class__

768

print " .getErrorMessage() =", reason.getErrorMessage()

769

print " .type =", reason.type

770

reactor.stop()

771

772

main()

773

</pre><div class="caption">Source listing - <a href="listings/pb/exc_client.py">listings/pb/exc_client.py</a></div></div>

774

775

776

% ./exc_client.py

777

got remote Exception

778

.__class__ = twisted.spread.pb.CopiedFailure

779

.getErrorMessage() = fall down go boom

780

.type = __main__.MyError

781

Main loop terminated.

782

</pre>

783

784

Oh, and what happens if you raise some other kind of exception? Something

785

that isn't subclassed from <code>pb.Error</code>? Well, those are

786

called <q>unexpected exceptions</q>, which make Twisted think that something

787

has really gone wrong. These will raise an exception on the

788

server side. This won't break the connection (the exception is

789

trapped, just like most exceptions that occur in response to network

790

traffic), but it will print out an unsightly stack trace on the server's

791

stderr with a message that says <q>Peer Will Receive PB Traceback</q>, just

792

as if the exception had happened outside a remotely-invokable method. (This

793

message will go the current log target, if <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.startLogging.html" title="twisted.python.log.startLogging">log.startLogging</a></code> was used to redirect it). The

794

client will get the same <code>Failure</code> object in either case, but

795

subclassing your exception from <code>pb.Error</code> is the way to tell

796

Twisted that you expect this sort of exception, and that it is ok to just

797

let the client handle it instead of also asking the server to complain. Look

798

at <code>exc_client.py</code> and change it to invoke <code>broken2()</code>

799

instead of <code>broken()</code> to see the change in the server's

800

behavior.

801

802

If you don't add an <code>errback</code> function to the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code>, then a remote

803

exception will still send a <code>Failure</code> object back over, but it

804

will get lodged in the <code>Deferred</code> with nowhere to go. When that

805

<code>Deferred</code> finally goes out of scope, the side that did

806

<code>callRemote</code> will emit a message about an <q>Unhandled error in

807

Deferred</q>, along with an ugly stack trace. It can't raise an exception at

808

that point (after all, the <code>callRemote</code> that triggered the

809

problem is long gone), but it will emit a traceback. So be a good programmer

810

and always add <code>errback</code> handlers, even if they are just

811

calls to <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.err.html" title="twisted.python.log.err">log.err</a></code>.

812

813

<h2>Try/Except blocks and <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.failure.Failure.trap.html" title="twisted.python.failure.Failure.trap">Failure.trap</a></code> <a name="auto5"/></h2>

814

815

To implement the equivalent of the Python try/except blocks (which can

816

trap particular kinds of exceptions and pass others <q>up</q> to

817

higher-level <code>try/except</code> blocks), you can use the

818

<code>.trap()</code> method in conjunction with multiple

819

<code>errback</code> handlers on the <code>Deferred</code>. Re-raising an

820

exception in an <code>errback</code> handler serves to pass that new

821

exception to the next handler in the chain. The <code>trap</code> method is

822

given a list of exceptions to look for, and will re-raise anything that

823

isn't on the list. Instead of passing unhandled exceptions <q>up</q> to an

824

enclosing <code>try</code> block, this has the effect of passing the

825

exception <q>off</q> to later <code>errback</code> handlers on the same

826

<code>Deferred</code>. The <code>trap</code> calls are used in chained

827

errbacks to test for each kind of exception in sequence.

828

829

<div class="py-listing"><pre> 1

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

#!/usr/bin/env python

851

852

853

# See LICENSE for details.

854

855

856

857

858

class MyException(pb.Error):

859

pass

860

861

class One(pb.Root):

862

def remote_fooMethod(self, arg):

863

if arg == "panic!":

864

raise MyException

865

return "response"

866

def remote_shutdown(self):

867

reactor.stop()

868

869

870

reactor.run()

871

</pre><div class="caption">Source listing - <a href="listings/pb/trap_server.py">listings/pb/trap_server.py</a></div></div>

872

<div class="py-listing"><pre> 1

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

#!/usr/bin/env python

961

962

963

# See LICENSE for details.

964

965

966

967

968

969

class MyException(pb.Error): pass

970

class MyOtherException(pb.Error): pass

971

972

class ScaryObject:

973

# not safe for serialization

974

pass

975

976

def worksLike(obj):

977

# the callback/errback sequence in class One works just like an

978

# asynchronous version of the following:

979

try:

980

response = obj.callMethod(name, arg)

981

except pb.DeadReferenceError:

982

print " stale reference: the client disconnected or crashed"

983

except jelly.InsecureJelly:

984

print " InsecureJelly: you tried to send something unsafe to them"

985

except (MyException, MyOtherException):

986

print " remote raised a MyException" # or MyOtherException

987

except:

988

print " something else happened"

989

else:

990

print " method successful, response:", response

991

992

class One:

993

def worked(self, response):

994

print " method successful, response:", response

995

def check_InsecureJelly(self, failure):

996

failure.trap(jelly.InsecureJelly)

997

print " InsecureJelly: you tried to send something unsafe to them"

998

return None

999

def check_MyException(self, failure):

1000

which = failure.trap(MyException, MyOtherException)

1001

if which == MyException:

1002

print " remote raised a MyException"

1003

else:

1004

print " remote raised a MyOtherException"

1005

return None

1006

def catch_everythingElse(self, failure):

1007

print " something else happened"

1008

log.err(failure)

1009

return None

1010

1011

def doCall(self, explanation, arg):

1012

print explanation

1013

try:

1014

deferred = self.remote.callRemote("fooMethod", arg)

1015

deferred.addCallback(self.worked)

1016

deferred.addErrback(self.check_InsecureJelly)

1017

deferred.addErrback(self.check_MyException)

1018

deferred.addErrback(self.catch_everythingElse)

1019

except pb.DeadReferenceError:

1020

print " stale reference: the client disconnected or crashed"

1021

1022

def callOne(self):

1023

self.doCall("callOne: call with safe object", "safe string")

1024

def callTwo(self):

1025

self.doCall("callTwo: call with dangerous object", ScaryObject())

1026

def callThree(self):

1027

self.doCall("callThree: call that raises remote exception", "panic!")

1028

def callShutdown(self):

1029

print "telling them to shut down"

1030

self.remote.callRemote("shutdown")

1031

def callFour(self):

1032

self.doCall("callFour: call on stale reference", "dummy")

1033

1034

def got_obj(self, obj):

1035

self.remote = obj

1036

reactor.callLater(1, self.callOne)

1037

reactor.callLater(2, self.callTwo)

1038

reactor.callLater(3, self.callThree)

1039

reactor.callLater(4, self.callShutdown)

1040

reactor.callLater(5, self.callFour)

1041

reactor.callLater(6, reactor.stop)

1042

1043

factory = pb.PBClientFactory()

1044

reactor.connectTCP("localhost", 8800, factory)

1045

deferred = factory.getRootObject()

1046

deferred.addCallback(One().got_obj)

1047

reactor.run()

1048

</pre><div class="caption">Source listing - <a href="listings/pb/trap_client.py">listings/pb/trap_client.py</a></div></div>

1049

1050

1051

% ./trap_client.py

1052

callOne: call with safe object

1053

method successful, response: response

1054

callTwo: call with dangerous object

1055

InsecureJelly: you tried to send something unsafe to them

1056

callThree: call that raises remote exception

1057

remote raised a MyException

1058

telling them to shut down

1059

callFour: call on stale reference

1060

stale reference: the client disconnected or crashed

1061

1062

</pre>

1063

1064

1065

In this example, <code>callTwo</code> tries to send an instance of a

1066

locally-defined class through <code>callRemote</code>. The default security

1067

model implemented by <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Jelly.html" title="twisted.spread.pb.Jelly">pb.Jelly</a></code>

1068

on the remote end will not allow unknown classes to be unserialized (i.e.

1069

taken off the wire as a stream of bytes and turned back into an object: a

1070

living, breathing instance of some class): one reason is that it does not

1071

know which local class ought to be used to create an instance that

1072

corresponds to the remote object<a href="#footnote-5" title="The naive approach of simply doing import SomeClass to match a remote caller who claims to have an object of type SomeClass could have nasty consequences for some modules that do significant operations in their __init__ methods (think telnetlib.Telnet(host='localhost', port='chargen'), or even more powerful classes that you have available in your server program). Allowing a remote entity to create arbitrary classes in your namespace is nearly equivalent to allowing them to run arbitrary code. The pb.InsecureJelly exception arises because the class being sent over the wire has not been registered with the serialization layer (known as jelly). The easiest way to make it possible to copy entire class instances over the wire is to have them inherit from pb.Copyable, and then to use setUnjellyableForClass(remoteClass, localClass) on the receiving side. See Passing Complex Types for an example."><super>5</super></a>.

1073

1074

The receiving end of the connection gets to decide what to accept and what

1075

to reject. It indicates its disapproval by raising a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.InsecureJelly.html" title="twisted.spread.pb.InsecureJelly">pb.InsecureJelly</a></code> exception. Because it occurs

1076

at the remote end, the exception is returned to the caller asynchronously,

1077

so an <code>errback</code> handler for the associated <code>Deferred</code>

1078

is run. That errback receives a <code>Failure</code> which wraps the

1079

<code>InsecureJelly</code>.

1080

1081

1082

Remember that <code>trap</code> re-raises exceptions that it wasn't asked

1083

to look for. You can only check for one set of exceptions per errback

1084

handler: all others must be checked in a subsequent handler.

1085

<code>check_MyException</code> shows how multiple kinds of exceptions can be

1086

checked in a single errback: give a list of exception types to

1087

<code>trap</code>, and it will return the matching member. In this case, the

1088

kinds of exceptions we are checking for (<code>MyException</code> and

1089

<code>MyOtherException</code>) may be raised by the remote end: they inherit

1090

from <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Error.html" title="twisted.spread.pb.Error">pb.Error</a></code>.

1091

1092

The handler can return <code>None</code> to terminate processing of the

1093

errback chain (to be precise, it switches to the callback that follows the

1094

errback; if there is no callback then processing terminates). It is a good

1095

idea to put an errback that will catch everything (no <code>trap</code>

1096

tests, no possible chance of raising more exceptions, always returns

1097

<code>None</code>) at the end of the chain. Just as with regular <code>try:

1098

except:</code> handlers, you need to think carefully about ways in which

1099

your errback handlers could themselves raise exceptions. The extra

1100

importance in an asynchronous environment is that an exception that falls

1101

off the end of the <code>Deferred</code> will not be signalled until that

1102

<code>Deferred</code> goes out of scope, and at that point may only cause a

1103

log message (which could even be thrown away if <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.startLogging.html" title="twisted.python.log.startLogging">log.startLogging</a></code> is not used to point it at

1104

stdout or a log file). In contrast, a synchronous exception that is not

1105

handled by any other <code>except:</code> block will very visibly terminate

1106

the program immediately with a noisy stack trace.

1107

1108

<code>callFour</code> shows another kind of exception that can occur

1109

while using <code>callRemote</code>: <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.DeadReferenceError.html" title="twisted.spread.pb.DeadReferenceError">pb.DeadReferenceError</a></code>. This one occurs when the

1110

remote end has disconnected or crashed, leaving the local side with a stale

1111

reference. This kind of exception happens to be reported right away (XXX: is

1112

this guaranteed? probably not), so must be caught in a traditional

1113

synchronous <code>try: except pb.DeadReferenceError</code> block.

1114

1115

Yet another kind that can occur is a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.PBConnectionLost.html" title="twisted.spread.pb.PBConnectionLost">pb.PBConnectionLost</a></code> exception. This occurs

1116

(asynchronously) if the connection was lost while you were waiting for a

1117

<code>callRemote</code> call to complete. When the line goes dead, all

1118

pending requests are terminated with this exception. Note that you have no

1119

way of knowing whether the request made it to the other end or not, nor how

1120

far along in processing it they had managed before the connection was

1121

lost. XXX: explain transaction semantics, find a decent reference.

1122

1123

<h2>Footnotes</h2><ol><li><a name="footnote-1">There are a few other classes

1124

that can bestow this ability, but pb.Referenceable is the easiest to

1125

understand; see 'flavors' below for details on the others.</a></li><li><a name="footnote-2">This can be overridden, by subclassing one of

1126

the Serializable flavors and defining custom serialization code for your

1127

class. See <a href="pb-copyable.html" shape="rect">Passing Complex Types</a> for

1128

details.</a></li><li><a name="footnote-3">The binary nature of this

1129

local vs. remote scheme works because you cannot give RemoteReferences to a

1130

third party. If you could, then your object A could go to B, B could give it to

1131

C, C might give it back to you, and you would be hard pressed to tell if the

1132

object lived in C's memory space, in B's, or if it was really your own object,

1133

tarnished and sullied after being handed down like a really ugly picture that

1134

your great aunt owned and which nobody wants but which nobody can bear to throw

1135

out. Ok, not really like that, but you get the idea.</a></li><li><a name="footnote-4">To be precise,

1136

the Failure will be sent if any exception is raised, not just

1137

pb.Error-derived ones. But the server will print ugly error messages if you

1138

raise ones that aren't derived from pb.Error.</a></li><li><a name="footnote-5">The naive approach of simply doing <code>import

1139

SomeClass</code> to match a remote caller who claims to have an object of

1140

type <q>SomeClass</q> could have nasty consequences for some modules that do

1141

significant operations in their <code>__init__</code> methods (think

1142

<code>telnetlib.Telnet(host='localhost', port='chargen')</code>, or even

1143

more powerful classes that you have available in your server program).

1144

Allowing a remote entity to create arbitrary classes in your namespace is

1145

nearly equivalent to allowing them to run arbitrary code.

1146

1147

The <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.InsecureJelly.html" title="twisted.spread.pb.InsecureJelly">pb.InsecureJelly</a></code>

1148

exception arises because the class being sent over the wire has not been

1149

registered with the serialization layer (known as <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.jelly.html" title="twisted.spread.jelly">jelly</a></code>). The easiest way to make it possible to

1150

copy entire class instances over the wire is to have them inherit from <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>, and then to use

1151

<code>setUnjellyableForClass(remoteClass, localClass)</code> on the

1152

receiving side. See <a href="pb-copyable.html" shape="rect">Passing Complex Types</a>

1153

for an example.</a></li></ol></div>

1154

1155

<a href="index.html">Index</a>

1156

Version: 10.0.0

1157

</body>

1158

</html>

b'\\ No newline at end of file'

Older »