~certify-web-dev/twisted/certify-staging

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: PB Copyable: Passing Complex Types</title><link href="stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">PB Copyable: Passing Complex Types</h1><div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Motivation</a></li><li><a href="#auto2">Passing Objects</a></li><ul><li><a href="#auto3">Security Options</a></li><li><a href="#auto4">What class to use?</a></li></ul><li><a href="#auto5">pb.Copyable</a></li><ul><li><a href="#auto6">Controlling the Copied State</a></li><li><a href="#auto7">Things To Watch Out For</a></li><li><a href="#auto8">More Information</a></li></ul><li><a href="#auto9">pb.Cacheable</a></li><ul><li><a href="#auto10">Example</a></li><li><a href="#auto11">More Information</a></li></ul></ol></div><div class="content"><h2>Overview<a name="auto0"></a></h2>This chapter focuses on how to use PB to pass complex types (specifically

<?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'>

<head>

<title>Twisted Documentation: PB Copyable: Passing Complex Types</title>

</head>

<h1 class="title">PB Copyable: Passing Complex Types</h1>

<div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Motivation</a></li><li><a href="#auto2">Passing Objects</a></li><ul><li><a href="#auto3">Security Options</a></li><li><a href="#auto4">What class to use?</a></li></ul><li><a href="#auto5">pb.Copyable</a></li><ul><li><a href="#auto6">Controlling the Copied State</a></li><li><a href="#auto7">Things To Watch Out For</a></li><li><a href="#auto8">More Information</a></li></ul><li><a href="#auto9">pb.Cacheable</a></li><ul><li><a href="#auto10">Example</a></li><li><a href="#auto11">More Information</a></li></ul></ol></div>

<h2>Overview<a name="auto0"/></h2>

This chapter focuses on how to use PB to pass complex types (specifically

class instances) to and from a remote process. The first section is on

simply copying the contents of an object to a remote process (<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>). The second covers how

to copy those contents once, then update them later when they change (<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Cacheable.html" title="twisted.spread.pb.Cacheable">Cacheable</a></code>).<h2>Motivation<a name="auto1"></a></h2>From the <a href="pb-usage.html">previous chapter</a>, you've seen how to

simply copying the contents of an object to a remote process (<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>). The second covers how

to copy those contents once, then update them later when they change (<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Cacheable.html" title="twisted.spread.pb.Cacheable">Cacheable</a></code>).

<h2>Motivation<a name="auto1"/></h2>

From the <a href="pb-usage.html" shape="rect">previous chapter</a>, you've seen how to

pass basic types to a remote process, by using them in the arguments or

return values of a <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Referenceable.callRemote.html" title="twisted.spread.pb.Referenceable.callRemote">callRemote</a></code> function. However,

return values of a <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Referenceable.callRemote.html" title="twisted.spread.pb.Referenceable.callRemote">callRemote</a></code> function. However,

if you've experimented with it, you may have discovered problems when trying

to pass anything more complicated than a primitive int/list/dict/string

type, or another <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">pb.Referenceable</a></code> object. At some point you want

type, or another <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Referenceable.html" title="twisted.spread.pb.Referenceable">pb.Referenceable</a></code> object. At some point you want

to pass entire objects between processes, instead of having to reduce them

down to dictionaries on one end and then re-instantiating them on the

other.<h2>Passing Objects<a name="auto2"></a></h2>The most obvious and straightforward way to send an object to a remote

other.

<h2>Passing Objects<a name="auto2"/></h2>

The most obvious and straightforward way to send an object to a remote

process is with something like the following code. It also happens that this

code doesn't work, as will be explained below.<pre class="python">

class LilyPond:

code doesn't work, as will be explained below.

<pre class="python">1

class LilyPond:

def __init__(self, frogs):

self.frogs = frogs

pond = LilyPond(12)

ref.callRemote("sendPond", pond)

</pre>If you try to run this, you might hope that a suitable remote end which

</pre>

If you try to run this, you might hope that a suitable remote end which

implements the <code>remote_sendPond</code> method would see that method get

invoked with an instance from the <code>LilyPond</code> class. But instead,

you'll encounter the dreaded <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.jelly.InsecureJelly.html" title="twisted.spread.jelly.InsecureJelly">InsecureJelly</a></code> exception. This is

you'll encounter the dreaded <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.jelly.InsecureJelly.html" title="twisted.spread.jelly.InsecureJelly">InsecureJelly</a></code> exception. This is

Twisted's way of telling you that you've violated a security restriction,

and that the receiving end refuses to accept your object.<h3>Security Options<a name="auto3"></a></h3>What's the big deal? What's wrong with just copying a class into another

process' namespace?Reversing the question might make it easier to see the issue: what is the

and that the receiving end refuses to accept your object.

<h3>Security Options<a name="auto3"/></h3>

What's the big deal? What's wrong with just copying a class into another

process' namespace?

Reversing the question might make it easier to see the issue: what is the

problem with accepting a stranger's request to create an arbitrary object in

your local namespace? The real question is how much power you are granting

them: what actions can they convince you to take on the basis of the bytes

they are sending you over that remote connection.Objects generally represent more power than basic types like strings and

they are sending you over that remote connection.

Objects generally represent more power than basic types like strings and

dictionaries because they also contain (or reference) code, which can modify

other data structures when executed. Once previously-trusted data is

subverted, the rest of the program is compromised.The built-in Python <q>batteries included</q> classes are relatively

subverted, the rest of the program is compromised.

The built-in Python <q>batteries included</q> classes are relatively

tame, but you still wouldn't want to let a foreign program use them to

create arbitrary objects in your namespace or on your computer. Imagine a

protocol that involved sending a file-like object with a <code>read()</code>

method that was supposed to used later to retrieve a document. Then imagine

what if that object were created with

<code>os.fdopen("~/.gnupg/secring.gpg")</code>. Or an instance of

<code>telnetlib.Telnet("localhost", "chargen")</code>. Classes you've written for your own program are likely to have far more

<code>telnetlib.Telnet("localhost", "chargen")</code>.

Classes you've written for your own program are likely to have far more

power. They may run code during <code>__init__</code>, or even have special

meaning simply because of their existence. A program might have

<code>User</code> objects to represent user accounts, and have a rule that

would probably add the object to a global list of known users). The simple

act of creating an object would give access to somebody. If you could be

tricked into creating a bad object, an unauthorized user would get

access.So object creation needs to be part of a system's security design. The

access.

So object creation needs to be part of a system's security design. The

100

dotted line between <q>trusted inside</q> and <q>untrusted outside</q> needs

101

to describe what may be done in response to outside events. One of those

102

events is the receipt of an object through a PB remote procedure call, which

103

is a request to create an object in your <q>inside</q> namespace. The

104

question is what to do in response to it. For this reason, you must

105

explicitly specific what remote classes will be accepted, and how their

local representatives are to be created.<h3>What class to use?<a name="auto4"></a></h3>Another basic question to answer before we can do anything useful with an

106

local representatives are to be created.

107

108

<h3>What class to use?<a name="auto4"/></h3>

109

110

Another basic question to answer before we can do anything useful with an

111

incoming serialized object is: what class should we create? The simplistic

112

answer is to create the <q>same kind</q> that was serialized on the sender's

113

end of the wire, but this is not as easy or as straightforward as you might

117

guarantee that the sender is even running Python! All we know on the

118

receiving end is a list of two things which describe the instance they are

119

trying to send us: the name of the class, and a representation of the

contents of the object.PB lets you specify the mapping from remote class names to local classes

with the <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.jelly.setUnjellyableForClass.html" title="twisted.spread.jelly.setUnjellyableForClass">setUnjellyableForClass</a></code> function<!--

--><a href="#footnote-1" title="Note that, in this context, unjelly is a verb with the opposite meaning of jelly. The verb to jelly means to serialize an object or data structure into a sequence of bytes (or other primitive transmittable/storable representation), while to unjelly means to unserialize the bytestream into a live object in the receiver's memory space. Unjellyable is a noun, (not an adjective), referring to the the class that serves as a destination or recipient of the unjellying process. A is unjellyable into B means that a serialized representation A (of some remote object) can be unserialized into a local object of type B. It is these objects B that are the Unjellyable second argument of the setUnjellyableForClass function.In particular, unjellyable does not mean cannot be jellied. Unpersistable means not persistable, but unjelly, unserialize, and unpickle mean to reverse the operations of jellying, serializing, and pickling."><super>1</super></a>.

120

contents of the object.

121

122

123

PB lets you specify the mapping from remote class names to local classes

124

with the <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.jelly.setUnjellyableForClass.html" title="twisted.spread.jelly.setUnjellyableForClass">setUnjellyableForClass</a></code> function<a href="#footnote-1" title="Note that, in this context, unjelly is a verb with the opposite meaning of jelly. The verb to jelly means to serialize an object or data structure into a sequence of bytes (or other primitive transmittable/storable representation), while to unjelly means to unserialize the bytestream into a live object in the receiver's memory space. Unjellyable is a noun, (not an adjective), referring to the the class that serves as a destination or recipient of the unjellying process. A is unjellyable into B means that a serialized representation A (of some remote object) can be unserialized into a local object of type B. It is these objects B that are the Unjellyable second argument of the setUnjellyableForClass function. In particular, unjellyable does not mean cannot be jellied. Unpersistable means not persistable, but unjelly, unserialize, and unpickle mean to reverse the operations of jellying, serializing, and pickling."><super>1</super></a>.

125

126

127

This function takes a remote/sender class reference (either the

131

the remote end sends an object, the class name that they transmit is looked

132

up in the table controlled by this function. If a matching class is found,

133

it is used to create the local object. If not, you get the

<code>InsecureJelly</code> exception.In general you expect both ends to share the same codebase: either you

134

<code>InsecureJelly</code> exception.

135

136

In general you expect both ends to share the same codebase: either you

137

control the program that is running on both ends of the wire, or both

138

programs share some kind of common language that is implemented in code

139

which exists on both ends. You wouldn't expect them to send you an object of

145

through namespace collisions between unrelated packages, version skew

146

between nodes that haven't been updated at the same rate, or a malicious

147

intruder trying to cause your code to fail in some interesting or

potentially vulnerable way.<h2>pb.Copyable<a name="auto5"></a></h2>Ok, enough of this theory. How do you send a fully-fledged object from

one side to the other?<div class="py-listing"><pre>

#! /usr/bin/python

148

potentially vulnerable way.

149

150

151

<h2>pb.Copyable<a name="auto5"/></h2>

152

153

Ok, enough of this theory. How do you send a fully-fledged object from

154

one side to the other?

155

156

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

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

#!/usr/bin/env python

214

215

216

# See LICENSE for details.

217

218

from twisted.spread import pb, jelly

219

from twisted.python import log

220

from twisted.internet import reactor

134

255

pond = CopyPond()

135

256

pond.setStuff("green", 7)

136

257

pond.countFrogs()

137

# class name:

138

print ".".join([pond.__class__.__module__, pond.__class__.__name__])

258

# class name:

259

print ".".join([pond.__class__.__module__, pond.__class__.__name__])

139

260

140

261

sender = Sender(pond)

141

262

factory = pb.PBClientFactory()

146

267

147

268

if __name__ == '__main__':

148

269

main()

149

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

150

"""PB copy receiver example.

270

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

271

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

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

# See LICENSE for details.

314

315

"""

316

PB copy receiver example.

151

317

152

318

This is a Twisted Application Configuration (tac) file. Run with e.g.

153

319

twistd -ny copy_receiver.tac

320

154

321

See the twistd(1) man page or

155

322

http://twistedmatrix.com/documents/current/howto/application for details.

156

323

"""

166

333

from copy_sender import LilyPond, CopyPond

167

334

168

335

169

#log.startLogging(sys.stdout)

170

336

#log.startLogging(sys.stdout)

337

171

338

class ReceiverPond(pb.RemoteCopy, LilyPond):

172

339

pass

173

340

pb.setUnjellyableForClass(CopyPond, ReceiverPond)

183

350

application = service.Application("copy_receiver")

184

351

internet.TCPServer(8800, pb.PBServerFactory(Receiver())).setServiceParent(

185

352

service.IServiceCollection(application))

186

</pre><div class="caption">Source listing - <a href="listings/pb/copy_receiver.tac">listings/pb/copy_receiver.tac</a></div></div>The sending side has a class called <code>LilyPond</code>. To make this

353

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

354

355

The sending side has a class called <code>LilyPond</code>. To make this

187

356

eligble for transport through <code>callRemote</code> (either as an

188

357

argument, a return value, or something referenced by either of those [like a

189

dictionary value]), it must inherit from one of the four <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.Serializable.html" title="twisted.spread.flavors.Serializable">Serializable</a></code> classes. In this section,

190

we focus on <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.Copyable.html" title="twisted.spread.flavors.Copyable">Copyable</a></code>.

358

dictionary value]), it must inherit from one of the four <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.Serializable.html" title="twisted.spread.flavors.Serializable">Serializable</a></code> classes. In this section,

359

we focus on <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.Copyable.html" title="twisted.spread.flavors.Copyable">Copyable</a></code>.

191

360

The copyable subclass of <code>LilyPond</code> is called

192

361

<code>CopyPond</code>. We create an instance of it and send it through

193

362

<code>callRemote</code> as an argument to the receiver's

196

365

<q>copy_sender.CopyPond</q> and some chunk of data that represents the

197

366

object's state. <code>pond.__class__.__module__</code> and

198

367

<code>pond.__class__.__name__</code> are used to derive the class name

199

string. The object's <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.flavors.Copyable.getStateToCopy.html" title="twisted.spread.pb.flavors.Copyable.getStateToCopy">getStateToCopy</a></code> method is

200

used to get the state: this is provided by <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>, and the default just retrieves

368

string. The object's <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.flavors.Copyable.getStateToCopy.html" title="twisted.spread.pb.flavors.Copyable.getStateToCopy">getStateToCopy</a></code> method is

369

used to get the state: this is provided by <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>, and the default just retrieves

201

370

<code>self.__dict__</code>. This works just like the optional

202

371

<code>__getstate__</code> method used by <code>pickle</code>. The pair of

203

name and state are sent over the wire to the receiver.The receiving end defines a local class named <code>ReceiverPond</code>

372

name and state are sent over the wire to the receiver.

373

374

The receiving end defines a local class named <code>ReceiverPond</code>

204

375

to represent incoming <code>LilyPond</code> instances. This class derives

205

376

from the sender's <code>LilyPond</code> class (with a fully-qualified name

206

377

of <code>copy_sender.LilyPond</code>), which specifies how we expect it to

207

378

behave. We trust that this is the same <code>LilyPond</code> class as the

208

379

sender used. (At the very least, we hope ours will be able to accept a state

209

created by theirs). It also inherits from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.RemoteCopy.html" title="twisted.spread.pb.RemoteCopy">pb.RemoteCopy</a></code>, which is a requirement for all

380

created by theirs). It also inherits from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.RemoteCopy.html" title="twisted.spread.pb.RemoteCopy">pb.RemoteCopy</a></code>, which is a requirement for all

210

381

classes that act in this local-representative role (those which are given to

211

382

the second argument of <code>setUnjellyableForClass</code>).

212

383

<code>RemoteCopy</code> provides the methods that tell the Jelly layer how

213

to create the local object from the incoming serialized state.Then <code>setUnjellyableForClass</code> is used to register the two

384

to create the local object from the incoming serialized state.

385

386

Then <code>setUnjellyableForClass</code> is used to register the two

214

387

classes. This has two effects: instances of the remote class (the first

215

388

argument) will be allowed in through the security layer, and instances of

216

389

the local class (the second argument) will be used to contain the state that

217

is transmitted when the sender serializes the remote object.When the receiver unserializes (<q>unjellies</q>) the object, it will

390

is transmitted when the sender serializes the remote object.

391

392

When the receiver unserializes (<q>unjellies</q>) the object, it will

218

393

create an instance of the local <code>ReceiverPond</code> class, and hand

219

394

the transmitted state (usually in the form of a dictionary) to that object's

220

<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.flavors.RemoteCopy.setCopyableState.html" title="twisted.spread.pb.flavors.RemoteCopy.setCopyableState">setCopyableState</a></code> method.

395

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.flavors.RemoteCopy.setCopyableState.html" title="twisted.spread.pb.flavors.RemoteCopy.setCopyableState">setCopyableState</a></code> method.

221

396

This acts just like the <code>__setstate__</code> method that

222

397

<code>pickle</code> uses when unserializing an object.

223

398

<code>getStateToCopy</code>/<code>setCopyableState</code> are distinct from

224

399

<code>__getstate__</code>/<code>__setstate__</code> to allow objects to be

225

400

persisted (across time) differently than they are transmitted (across

226

[memory]space).When this is run, it produces the following output:<pre class="shell">

401

[memory]space).

402

403

When this is run, it produces the following output:

404

405

227

406

[-] twisted.spread.pb.PBServerFactory starting on 8800

228

407

[-] Starting factory <twisted.spread.pb.PBServerFactory instance at

229

408

0x406159cc>

230

409

[Broker,0,127.0.0.1] got pond: <__builtin__.ReceiverPond instance at

231

410

0x406ec5ec>

232

411

[Broker,0,127.0.0.1] 7 frogs

233

</pre><pre class="shell">

412

</pre>

413

414

234

415

% ./copy_sender.py

235

416

7 frogs

236

417

copy_sender.CopyPond

237

418

pond arrived safe and sound

238

419

Main loop terminated.

239

420

240

</pre><h3>Controlling the Copied State<a name="auto6"></a></h3>By overriding <code>getStateToCopy</code> and

421

</pre>

422

423

424

425

<h3>Controlling the Copied State<a name="auto6"/></h3>

426

427

By overriding <code>getStateToCopy</code> and

241

428

<code>setCopyableState</code>, you can control how the object is transmitted

242

429

over the wire. For example, you might want perform some data-reduction:

243

430

pre-compute some results instead of sending all the raw data over the wire.

244

431

Or you could replace references to a local object on the sender's side with

245

432

markers before sending, then upon receipt replace those markers with

246

433

references to a receiver-side proxy that could perform the same operations

247

against a local cache of data.Another good use for <code>getStateToCopy</code> is to implement

434

against a local cache of data.

435

436

Another good use for <code>getStateToCopy</code> is to implement

248

437

<q>local-only</q> attributes: data that is only accessible by the local

249

438

process, not to any remote users. For example, a <code>.password</code>

250

439

attribute could be removed from the object state before sending to a remote

252

441

unchanged from a round trip, this could be used to build a

253

442

challenge-response system (in fact PB does this with

254

443

<code>pb.Referenceable</code> objects to implement authorization as

255

described <a href="pb-cred.html">here</a>).Whatever <code>getStateToCopy</code> returns from the sending object will

444

described <a href="pb-cred.html" shape="rect">here</a>).

445

446

Whatever <code>getStateToCopy</code> returns from the sending object will

256

447

be serialized and sent over the wire; <code>setCopyableState</code> gets

257

448

whatever comes over the wire and is responsible for setting up the state of

258

the object it lives in.<div class="py-listing"><pre>

259

#! /usr/bin/python

260

449

the object it lives in.

450

451

452

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

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

#!/usr/bin/env python

482

483

484

# See LICENSE for details.

485

261

486

262

487

263

488

class FrogPond:

282

507

return self.frogsAndToads

283

508

284

509

pb.setUnjellyableForClass(SenderPond, ReceiverPond)

285

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

286

#! /usr/bin/python

287

510

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

511

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

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

#!/usr/bin/env python

556

557

558

# See LICENSE for details.

559

288

560

289

561

290

562

323

595

324

596

if __name__ == '__main__':

325

597

main()

326

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

327

#! /usr/bin/python

328

598

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

599

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

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

#!/usr/bin/env python

621

622

623

# See LICENSE for details.

624

329

625

from twisted.application import service, internet

330

626

331

627

342

638

application = service.Application("copy_receiver")

343

639

344

640

service.IServiceCollection(application))

345

</pre><div class="caption">Source listing - <a href="listings/pb/copy2_receiver.py">listings/pb/copy2_receiver.py</a></div></div>In this example, the classes are defined in a separate source file, which

641

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

642

643

In this example, the classes are defined in a separate source file, which

346

644

also sets up the binding between them. The <code>SenderPond</code> and

347

645

<code>ReceiverPond</code> are unrelated save for this binding: they happen

348

646

to implement the same methods, but use different internal instance variables

349

to accomplish them.The recipient of the object doesn't even have to import the class

647

to accomplish them.

648

649

The recipient of the object doesn't even have to import the class

350

650

definition into their namespace. It is sufficient that they import the class

351

651

definition (and thus execute the <code>setUnjellyableForClass</code>

352

652

statement). The Jelly layer remembers the class definition until a matching

353

653

object is received. The sender of the object needs the definition, of

354

course, to create the object in the first place.When run, the <code>copy2</code> example emits the following:<pre class="shell">

654

course, to create the object in the first place.

655

656

When run, the <code>copy2</code> example emits the following:

657

658

355

659

% twistd -n -y copy2_receiver.py

356

660

[-] twisted.spread.pb.PBServerFactory starting on 8800

357

661

[-] Starting factory <twisted.spread.pb.PBServerFactory instance at

359

663

[Broker,0,127.0.0.1] got pond: <copy2_classes.ReceiverPond instance at

360

664

0x406eb2ac>

361

665

[Broker,0,127.0.0.1] count 7

362

</pre><pre class="shell">

666

</pre>

667

668

363

669

% ./copy2_sender.py

364

670

count 7

365

671

pond arrived safe and sound

366

672

Main loop terminated.

367

673

368

</pre><h3>Things To Watch Out For<a name="auto7"></a></h3><ul><li>The first argument to <code>setUnjellyableForClass</code> must refer

674

</pre>

675

676

677

678

<h3>Things To Watch Out For<a name="auto7"/></h3>

679

680

<ul>

681

682

<li>The first argument to <code>setUnjellyableForClass</code> must refer

369

683

to the class as known by the sender. The sender has no way of

370

684

knowing about how your local <code>import</code> statements are set up,

371

685

and Python's flexible namespace semantics allow you to access the same

376

690

defined together, with the <code>setUnjellyableForClass</code> immediately

377

691

following them. (XXX: this works, but does this really get the right names

378

692

into the table? Or does it only work because both are defined in the same

379

(wrong) place?)</li><li>The class that is sent must inherit from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>. The class that is registered to

380

receive it must inherit from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.RemoteCopy.html" title="twisted.spread.pb.RemoteCopy">pb.RemoteCopy</a></code><a href="#footnote-2" title="pb.RemoteCopy is actually defined as flavors.RemoteCopy, but pb.RemoteCopy is the preferred way to access it"><super>2</super></a>. </li><li>The same class can be used to send and receive. Just have it inherit

693

(wrong) place?)</li>

694

695

<li>The class that is sent must inherit from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>. The class that is registered to

696

receive it must inherit from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.RemoteCopy.html" title="twisted.spread.pb.RemoteCopy">pb.RemoteCopy</a></code><a href="#footnote-2" title="pb.RemoteCopy is actually defined as flavors.RemoteCopy, but pb.RemoteCopy is the preferred way to access it"><super>2</super></a>. </li>

697

698

<li>The same class can be used to send and receive. Just have it inherit

381

699

from both <code>pb.Copyable</code> and <code>pb.RemoteCopy</code>. This

382

700

will also make it possible to send the same class symmetrically back and

383

701

forth over the wire. But don't get confused about when it is coming (and

384

702

using <code>setCopyableState</code>) versus when it is going (using

385

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

703

<code>getStateToCopy</code>).</li>

704

705

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

386

706

exceptions are raised by the receiving end. They will be delivered

387

707

asynchronously to an <code>errback</code> handler. If you do not add one

388

708

to the <code>Deferred</code> returned by <code>callRemote</code>, then you

389

will never receive notification of the problem. </li><li>The class that is derived from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.RemoteCopy.html" title="twisted.spread.pb.RemoteCopy">pb.RemoteCopy</a></code> will be created using a

709

will never receive notification of the problem. </li>

710

711

<li>The class that is derived from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.RemoteCopy.html" title="twisted.spread.pb.RemoteCopy">pb.RemoteCopy</a></code> will be created using a

390

712

constructor <code>__init__</code> method that takes no arguments. All

391

713

setup must be performed in the <code>setCopyableState</code> method. As

392

the docstring on <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.RemoteCopy.html" title="twisted.spread.flavors.RemoteCopy">RemoteCopy</a></code> says, don't implement a

714

the docstring on <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.RemoteCopy.html" title="twisted.spread.flavors.RemoteCopy">RemoteCopy</a></code> says, don't implement a

393

715

constructor that requires arguments in a subclass of

394

716

<code>RemoteCopy</code>. XXX: check this, the code around

395

717

jelly._Unjellier.unjelly:489 tries to avoid calling <code>__init__</code>

396

just in case the constructor requires args. </li></ul><h3>More Information<a name="auto8"></a></h3><ul><li><code>pb.Copyable</code> is mostly implemented in <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.html" title="twisted.spread.flavors">twisted.spread.flavors</a></code>, and the docstrings there are the

397

best source of additional information.</li><li><code>Copyable</code> is also used in <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.web.distrib.html" title="twisted.web.distrib">twisted.web.distrib</a></code> to deliver HTTP requests to other

718

just in case the constructor requires args. </li>

719

720

</ul>

721

722

<h3>More Information<a name="auto8"/></h3>

723

724

<ul>

725

726

<li> <code>pb.Copyable</code> is mostly implemented in <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.html" title="twisted.spread.flavors">twisted.spread.flavors</a></code>, and the docstrings there are the

727

best source of additional information.</li>

728

729

<li><code>Copyable</code> is also used in <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.web.distrib.html" title="twisted.web.distrib">twisted.web.distrib</a></code> to deliver HTTP requests to other

398

730

programs for rendering, allowing subtrees of URL space to be delegated to

399

multiple programs (on multiple machines).</li><li><code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.manhole.explorer.html" title="twisted.manhole.explorer">twisted.manhole.explorer</a></code> also uses

731

multiple programs (on multiple machines).</li>

732

733

<li><code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.manhole.explorer.html" title="twisted.manhole.explorer">twisted.manhole.explorer</a></code> also uses

400

734

<code>Copyable</code> to distribute debugging information from the program

401

under test to the debugging tool.</li></ul><h2>pb.Cacheable<a name="auto9"></a></h2>Sometimes the object you want to send to the remote process is big and

735

under test to the debugging tool.</li>

736

737

</ul>

738

739

740

<h2>pb.Cacheable<a name="auto9"/></h2>

741

742

Sometimes the object you want to send to the remote process is big and

402

743

slow. <q>big</q> means it takes a lot of data (storage, network bandwidth,

403

744

processing) to represent its state. <q>slow</q> means that state doesn't

404

745

change very frequently. It may be more efficient to send the full state only

405

746

once, the first time it is needed, then afterwards only send the differences

406

or changes in state whenever it is modified. The <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Cacheable.html" title="twisted.spread.pb.Cacheable">pb.Cacheable</a></code> class provides a framework to

407

implement this.<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Cacheable.html" title="twisted.spread.pb.Cacheable">pb.Cacheable</a></code> is derived

408

from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>, so it is

747

or changes in state whenever it is modified. The <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Cacheable.html" title="twisted.spread.pb.Cacheable">pb.Cacheable</a></code> class provides a framework to

748

implement this.

749

750

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Cacheable.html" title="twisted.spread.pb.Cacheable">pb.Cacheable</a></code> is derived

751

from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Copyable.html" title="twisted.spread.pb.Copyable">pb.Copyable</a></code>, so it is

409

752

based upon the idea of an object's state being captured on the sending side,

410

753

and then turned into a new object on the receiving side. This is extended to

411

have an object <q>publishing</q> on the sending side (derived from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Cacheable.html" title="twisted.spread.pb.Cacheable">pb.Cacheable</a></code>), matched with one

412

<q>observing</q> on the receiving side (derived from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.RemoteCache.html" title="twisted.spread.pb.RemoteCache">pb.RemoteCache</a></code>).To effectively use <code>pb.Cacheable</code>, you need to isolate changes

754

have an object <q>publishing</q> on the sending side (derived from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Cacheable.html" title="twisted.spread.pb.Cacheable">pb.Cacheable</a></code>), matched with one

755

<q>observing</q> on the receiving side (derived from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.RemoteCache.html" title="twisted.spread.pb.RemoteCache">pb.RemoteCache</a></code>).

756

757

To effectively use <code>pb.Cacheable</code>, you need to isolate changes

413

758

to your object into accessor functions (specifically <q>setter</q>

414

759

functions). Your object needs to get control every single time some

415

attribute is changed<a href="#footnote-3" title="of course you could be clever and add a hook to __setattr__, along with magical change-announcing subclasses of the usual builtin types, to detect changes that result from normal = set operations. The semi-magical property attributes that were introduced in Python-2.2 could be useful too. The result might be hard to maintain or extend, though."><super>3</super></a>.You derive your sender-side class from <code>pb.Cacheable</code>, and you

416

add two methods: <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.Cacheable.getStateToCacheAndObserveFor.html" title="twisted.spread.flavors.Cacheable.getStateToCacheAndObserveFor">getStateToCacheAndObserveFor</a></code>

417

and <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.Cacheable.stoppedObserving.html" title="twisted.spread.flavors.Cacheable.stoppedObserving">stoppedObserving</a></code>. The first

760

761

762

You derive your sender-side class from <code>pb.Cacheable</code>, and you

763

add two methods: <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.Cacheable.getStateToCacheAndObserveFor.html" title="twisted.spread.flavors.Cacheable.getStateToCacheAndObserveFor">getStateToCacheAndObserveFor</a></code>

764

and <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.Cacheable.stoppedObserving.html" title="twisted.spread.flavors.Cacheable.stoppedObserving">stoppedObserving</a></code>. The first

418

765

is called when a remote caching reference is first created, and retrieves

419

766

the data with which the cache is first filled. It also provides an

420

object called the <q>observer</q><!--

421

422

--><a href="#footnote-4" title="this is actually a RemoteCacheObserver, but it isn't very useful to subclass or modify, so simply treat it as a little demon that sits in your pb.Cacheable class and helps you distribute change notifications. The only useful thing to do with it is to run its callRemote method, which acts just like a normal pb.Referenceable's method of the same name."><super>4</super></a>

767

object called the <q>observer</q><a href="#footnote-4" title="this is actually a RemoteCacheObserver, but it isn't very useful to subclass or modify, so simply treat it as a little demon that sits in your pb.Cacheable class and helps you distribute change notifications. The only useful thing to do with it is to run its callRemote method, which acts just like a normal pb.Referenceable's method of the same name."><super>4</super></a>

423

768

424

769

that points at that receiver-side cache. Every time the state of the object

425

770

is changed, you give a message to the observer, informing them of the

426

771

change. The other method, <code>stoppedObserving</code>, is called when the

427

remote cache goes away, so that you can stop sending updates.On the receiver end, you make your cache class inherit from <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.RemoteCache.html" title="twisted.spread.pb.RemoteCache">pb.RemoteCache</a></code>, and implement the

772

remote cache goes away, so that you can stop sending updates.

773

774

On the receiver end, you make your cache class inherit from <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.RemoteCache.html" title="twisted.spread.pb.RemoteCache">pb.RemoteCache</a></code>, and implement the

428

775

<code>setCopyableState</code> as you would for a <code>pb.RemoteCopy</code>

429

776

object. In addition, you must implement methods to receive the updates sent

430

777

to the observer by the <code>pb.Cacheable</code>: these methods should have

431

778

names that start with <code>observe_</code>, and match the

432

779

<code>callRemote</code> invocations from the sender side just as the usual

433

780

<code>remote_*</code> and <code>perspective_*</code> methods match normal

434

<code>callRemote</code> calls. The first time a reference to the <code>pb.Cacheable</code> object is

781

<code>callRemote</code> calls.

782

783

The first time a reference to the <code>pb.Cacheable</code> object is

435

784

sent to any particular recipient, a sender-side Observer will be created for

436

785

it, and the <code>getStateToCacheAndObserveFor</code> method will be called

437

786

to get the current state and register the Observer. The state which that

438

787

returns is sent to the remote end and turned into a local representation

439

788

using <code>setCopyableState</code> just like <code>pb.RemoteCopy</code>,

440

described above (in fact it inherits from that class). After that, your <q>setter</q> functions on the sender side should call

789

described above (in fact it inherits from that class).

790

791

After that, your <q>setter</q> functions on the sender side should call

441

792

<code>callRemote</code> on the Observer, which causes <code>observe_*</code>

442

793

methods to run on the receiver, which are then supposed to update the

443

receiver-local (cached) state.When the receiver stops following the cached object and the last

794

receiver-local (cached) state.

795

796

When the receiver stops following the cached object and the last

444

797

reference goes away, the <code>pb.RemoteCache</code> object can be freed.

445

798

Just before it dies, it tells the sender side it no longer cares about the

446

799

original object. When that reference count goes to zero, the

447

800

Observer goes away and the <code>pb.Cacheable</code> object can stop

448

announcing every change that takes place. The <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.Cacheable.stoppedObserving.html" title="twisted.spread.flavors.Cacheable.stoppedObserving">stoppedObserving</a></code> method is

801

announcing every change that takes place. The <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.Cacheable.stoppedObserving.html" title="twisted.spread.flavors.Cacheable.stoppedObserving">stoppedObserving</a></code> method is

449

802

used to tell the <code>pb.Cacheable</code> that the Observer has gone

450

away.With the <code>pb.Cacheable</code> and <code>pb.RemoteCache</code>

803

away.

804

805

With the <code>pb.Cacheable</code> and <code>pb.RemoteCache</code>

451

806

classes in place, bound together by a call to

452

807

<code>pb.setUnjellyableForClass</code>, all that remains is to pass a

453

808

reference to your <code>pb.Cacheable</code> over the wire to the remote end.

454

809

The corresponding <code>pb.RemoteCache</code> object will automatically be

455

810

created, and the matching methods will be used to keep the receiver-side

456

slave object in sync with the sender-side master object.<h3>Example<a name="auto10"></a></h3>Here is a complete example, in which the <code>MasterDuckPond</code> is

811

slave object in sync with the sender-side master object.

812

813

<h3>Example<a name="auto10"/></h3>

814

815

Here is a complete example, in which the <code>MasterDuckPond</code> is

457

816

controlled by the sending side, and the <code>SlaveDuckPond</code> is a

458

cache that tracks changes to the master:<div class="py-listing"><pre>

459

#! /usr/bin/python

460

817

cache that tracks changes to the master:

818

819

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

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

#!/usr/bin/env python

863

864

865

# See LICENSE for details.

866

461

867

462

868

463

869

class MasterDuckPond(pb.Cacheable):

474

880

for o in self.observers: o.callRemote('removeDuck', duck)

475

881

def getStateToCacheAndObserveFor(self, perspective, observer):

476

882

self.observers.append(observer)

477

# you should ignore pb.Cacheable-specific state, like self.observers

478

return self.ducks # in this case, just a list of ducks

883

# you should ignore pb.Cacheable-specific state, like self.observers

884

return self.ducks # in this case, just a list of ducks

479

885

def stoppedObserving(self, perspective, observer):

480

886

self.observers.remove(observer)

481

887

482

888

class SlaveDuckPond(pb.RemoteCache):

483

# This is a cache of a remote MasterDuckPond

484

def count(self):

889

# This is a cache of a remote MasterDuckPond

890

def count(self):

485

891

return len(self.cacheducks)

486

892

def getDucks(self):

487

893

return self.cacheducks

496

902

self.cacheducks.remove(deadDuck)

497

903

498

904

pb.setUnjellyableForClass(MasterDuckPond, SlaveDuckPond)

499

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

500

#! /usr/bin/python

501

905

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

906

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

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

#!/usr/bin/env python

957

958

959

# See LICENSE for details.

960

502

961

503

962

504

963

544

1003

545

1004

if __name__ == '__main__':

546

1005

main()

547

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

548

#! /usr/bin/python

549

1006

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

1007

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

1008

1009

1010

1011

1012

1013

1014

1015

1016

1017

1018

1019

1020

1021

1022

1023

1024

1025

1026

1027

1028

1029

1030

1031

1032

1033

1034

1035

#!/usr/bin/env python

1036

1037

1038

# See LICENSE for details.

1039

550

1040

551

1041

552

1042

560

1050

def remote_checkDucks(self):

561

1051

print "[%d] ducks: " % self.pond.count(), self.pond.getDucks()

562

1052

def remote_ignorePond(self):

563

# stop watching the pond

564

print "dropping pond"

565

# gc causes __del__ causes 'decache' msg causes stoppedObserving

566

self.pond = None

1053

# stop watching the pond

1054

print "dropping pond"

1055

# gc causes __del__ causes 'decache' msg causes stoppedObserving

1056

self.pond = None

567

1057

def remote_shutdown(self):

568

1058

reactor.stop()

569

1059

570

1060

application = service.Application("copy_receiver")

571

1061

572

1062

service.IServiceCollection(application))

573

</pre><div class="caption">Source listing - <a href="listings/pb/cache_receiver.py">listings/pb/cache_receiver.py</a></div></div>When run, this example emits the following:<pre class="shell">

1063

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

1064

When run, this example emits the following:

1065

1066

574

1067

% twistd -n -y cache_receiver.py

575

1068

[-] twisted.spread.pb.PBServerFactory starting on 8800

576

1069

[-] Starting factory <twisted.spread.pb.PBServerFactory instance at

585

1078

[Broker,0,127.0.0.1] [2] ducks: ['two duck', 'ugly duckling']

586

1079

[Broker,0,127.0.0.1] dropping pond

587

1080

588

</pre><pre class="shell">

1081

</pre>

1082

1083

589

1084

% ./cache_sender.py

590

1085

I have [2] ducks

591

1086

I have [3] ducks

592

1087

I have [2] ducks

593

1088

Main loop terminated.

594

1089

595

</pre>Points to notice:<ul><li>There is one <code>Observer</code> for each remote program that holds

1090

</pre>

1091

1092

1093

Points to notice:

1094

1095

<ul>

1096

<li>There is one <code>Observer</code> for each remote program that holds

596

1097

an active reference. Multiple references inside the same program don't

597

1098

matter: the serialization layer notices the duplicates and does the

598

1099

appropriate reference counting<a href="#footnote-5" title="this applies to multiple references through the same Broker. If you've managed to make multiple TCP connections to the same program, you deserve whatever you get."><super>5</super></a>.

599

</li><li>Multiple Observers need to be kept in a list, and all of them need to

1100

</li>

1101

1102

<li>Multiple Observers need to be kept in a list, and all of them need to

600

1103

be updated when something changes. By sending the initial state at the

601

1104

same time as you add the observer to the list, in a single atomic action

602

1105

that cannot be interrupted by a state change, you insure that you can send

603

the same status update to all the observers.</li><li>The <code>observer.callRemote</code> calls can still fail. If the

1106

the same status update to all the observers.</li>

1107

1108

<li>The <code>observer.callRemote</code> calls can still fail. If the

604

1109

remote side has disconnected very recently and

605

1110

<code>stoppedObserving</code> has not yet been called, you may get a

606

1111

<code>DeadReferenceError</code>. It is a good idea to add an errback to

607

1112

those <code>callRemote</code>s to throw away such an error. This is a

608

1113

useful idiom:

609

1114

610

611

observer.callRemote('foo', arg).addErrback(lambda f: None)

1115

<pre class="python">1

1116

observer.callRemote('foo', arg).addErrback(lambda f: None)

612

1117

</pre>

613

1118

614

(XXX: verify that this is actually a concern)</li><li><code>getStateToCacheAndObserverFor</code> must return some object

1119

(XXX: verify that this is actually a concern)</li>

1120

1121

<li><code>getStateToCacheAndObserverFor</code> must return some object

615

1122

that represents the current state of the object. This may simply be the

616

1123

object's <code>__dict__</code> attribute. It is a good idea to remove the

617

1124

<code>pb.Cacheable</code>-specific members of it before sending it to the

618

1125

remote end. The list of Observers, in particular, should be left out, to

619

1126

avoid dizzying recursive Cacheable references. The mind boggles as to the

620

potential consequences of leaving in such an item.</li><li>A <code>perspective</code> argument is available to

1127

potential consequences of leaving in such an item.</li>

1128

1129

<li>A <code>perspective</code> argument is available to

621

1130

<code>getStateToCacheAndObserveFor</code>, as well as

622

1131

<code>stoppedObserving</code>. I think the purpose of this is to allow

623

1132

viewer-specific changes to the way the cache is updated. If all remote

624

viewers are supposed to see the same data, it can be ignored.</li></ul>XXX: understand, then explain use of varying cached state depending upon

625

perspective.<h3>More Information<a name="auto11"></a></h3><ul><li>The best source for information comes from the docstrings in <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.html" title="twisted.spread.flavors">twisted.spread.flavors</a></code>, where <code>pb.Cacheable</code>

626

is implemented.</li><li><code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.manhole.explorer.html" title="twisted.manhole.explorer">twisted.manhole.explorer</a></code> uses

1133

viewers are supposed to see the same data, it can be ignored.</li>

1134

1135

</ul>

1136

1137

1138

XXX: understand, then explain use of varying cached state depending upon

1139

perspective.

1140

1141

<h3>More Information<a name="auto11"/></h3>

1142

1143

<ul>

1144

<li>The best source for information comes from the docstrings in <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.html" title="twisted.spread.flavors">twisted.spread.flavors</a></code>, where <code>pb.Cacheable</code>

1145

is implemented.</li>

1146

1147

<li><code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.manhole.explorer.html" title="twisted.manhole.explorer">twisted.manhole.explorer</a></code> uses

627

1148

<code>Cacheable</code>, and does some fairly interesting things with it.

628

1149

(XXX: I've heard explorer is currently broken, it might not be a good

629

example to recommend)</li><li>The <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.publish.html" title="twisted.spread.publish">spread.publish</a></code> module also

1150

example to recommend)</li>

1151

1152

<li>The <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.publish.html" title="twisted.spread.publish">spread.publish</a></code> module also

630

1153

uses <code>Cacheable</code>, and might be a source of further

631

information.</li></ul><h2>Footnotes</h2><ol><li><a name="footnote-1">Note that, in this context, <q>unjelly</q> is

1154

information.</li>

1155

</ul>

1156

1157

1158

1159

<h2>Footnotes</h2><ol><li><a name="footnote-1"> Note that, in this context, <q>unjelly</q> is

632

1160

a verb with the opposite meaning of <q>jelly</q>. The verb <q>to jelly</q>

633

1161

means to serialize an object or data structure into a sequence of bytes (or

634

1162

other primitive transmittable/storable representation), while <q>to

639

1167

that a serialized representation A (of some remote object) can be

640

1168

unserialized into a local object of type B. It is these objects <q>B</q>

641

1169

that are the <q>Unjellyable</q> second argument of the

642

<code>setUnjellyableForClass</code> function.In particular, <q>unjellyable</q> does not mean <q>cannot be

643

jellied</q>. <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.jelly.Unpersistable.html" title="twisted.spread.jelly.Unpersistable">Unpersistable</a></code> means <q>not

1170

<code>setUnjellyableForClass</code> function.

1171

1172

In particular, <q>unjellyable</q> does not mean <q>cannot be

1173

jellied</q>. <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.jelly.Unpersistable.html" title="twisted.spread.jelly.Unpersistable">Unpersistable</a></code> means <q>not

644

1174

persistable</q>, but <q>unjelly</q>, <q>unserialize</q>, and <q>unpickle</q>

645

1175

mean to reverse the operations of <q>jellying</q>, <q>serializing</q>, and

646

<q>pickling</q>.</a></li><li><a name="footnote-2"><code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.RemoteCopy.html" title="twisted.spread.pb.RemoteCopy">pb.RemoteCopy</a></code> is actually defined

647

as <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.RemoteCopy.html" title="twisted.spread.flavors.RemoteCopy">flavors.RemoteCopy</a></code>, but

648

<code>pb.RemoteCopy</code> is the preferred way to access it</a></li><li><a name="footnote-3">of course you could be clever and

1176

<q>pickling</q>. </a></li><li><a name="footnote-2"><code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.RemoteCopy.html" title="twisted.spread.pb.RemoteCopy">pb.RemoteCopy</a></code> is actually defined

1177

as <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.RemoteCopy.html" title="twisted.spread.flavors.RemoteCopy">flavors.RemoteCopy</a></code>, but

1178

<code>pb.RemoteCopy</code> is the preferred way to access it</a></li><li><a name="footnote-3">of course you could be clever and

649

1179

add a hook to <code>__setattr__</code>, along with magical change-announcing

650

1180

subclasses of the usual builtin types, to detect changes that result from

651

1181

normal <q>=</q> set operations. The semi-magical <q>property attributes</q>

652

1182

that were introduced in Python-2.2 could be useful too. The result might be

653

hard to maintain or extend, though.</a></li><li><a name="footnote-4"> this is actually a <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.flavors.RemoteCacheObserver.html" title="twisted.spread.flavors.RemoteCacheObserver">RemoteCacheObserver</a></code>, but it isn't very

1183

hard to maintain or extend, though.</a></li><li><a name="footnote-4"> this is actually a <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.flavors.RemoteCacheObserver.html" title="twisted.spread.flavors.RemoteCacheObserver">RemoteCacheObserver</a></code>, but it isn't very

654

1184

useful to subclass or modify, so simply treat it as a little demon that sits

655

1185

in your <code>pb.Cacheable</code> class and helps you distribute change

656

1186

notifications. The only useful thing to do with it is to run its

657

1187

<code>callRemote</code> method, which acts just like a normal

658

<code>pb.Referenceable</code>'s method of the same name.</a></li><li><a name="footnote-5">this applies to

659

multiple references through the same <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.spread.pb.Broker.html" title="twisted.spread.pb.Broker">Broker</a></code>. If you've managed to make multiple

660

TCP connections to the same program, you deserve whatever you get.</a></li></ol></div><a href="index.html">Index</a>Version: 8.2.0</body></html>

b'\\ No newline at end of file'

1188

<code>pb.Referenceable</code>'s method of the same name.</a></li><li><a name="footnote-5">this applies to

1189

multiple references through the same <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.spread.pb.Broker.html" title="twisted.spread.pb.Broker">Broker</a></code>. If you've managed to make multiple

1190

TCP connections to the same program, you deserve whatever you get.</a></li></ol></div>

1191

1192

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

1193

Version: 9.0.0

1194

</body>

1195

</html>

b'\\ No newline at end of file'

Older »