~justin-fathomdb/nova/justinsb-openstack-api-volumes

<?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: Introduction to Perspective Broker</title>

</head>

<h1 class="title">Introduction to Perspective Broker</h1>

<div class="toc"><ol><li><a href="#auto0">Introduction</a></li><li><a href="#auto1">Object Roadmap</a></li><ul><li><a href="#auto2">Subclassing and Implementing</a></li></ul><li><a href="#auto3">Things you can Call Remotely</a></li><li><a href="#auto4">Things you can Copy Remotely</a></li></ol></div>

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

Suppose you find yourself in control of both ends of the wire: you

have two programs that need to talk to each other, and you get to use any

protocol you want. If you can think of your problem in terms of objects that

need to make method calls on each other, then chances are good that you can

use twisted's Perspective Broker protocol rather than trying to shoehorn

your needs into something like HTTP, or implementing yet another RPC

mechanism<a href="#footnote-1" title="Most of Twisted is like this. Hell, most of unix is like this: if you think it would be useful, someone else has probably thought that way in the past, and acted on it, and you can take advantage of the tool they created to solve the same problem you're facing now."><super>1</super></a>.

The Perspective Broker system (abbreviated <q>PB</q>, spawning numerous

sandwich-related puns) is based upon a few central concepts:

<ul>

<li>serialization: taking fairly arbitrary objects and types,

turning them into a chunk of bytes, sending them over a wire, then

reconstituting them on the other end. By keeping careful track of object

ids, the serialized objects can contain references to other objects and

the remote copy will still be useful. </li>

<li>remote method calls: doing something to a local object and

causing a method to get run on a distant one. The local object is called 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>, and you

<q>do something</q> by running its <code>.callRemote</code> method.

</li>

</ul>

This document will contain several examples that will (hopefully) appear

redundant and verbose once you've figured out what's going on. To begin

with, much of the code will just be labelled <q>magic</q>: don't worry about how

these parts work yet. It will be explained more fully later.

<h2>Object Roadmap<a name="auto1"/></h2>

To start with, here are the major classes, interfaces, and

functions involved in PB, with links to the file where they are

defined (all of which are under twisted/, of course). Don't worry

about understanding what they all do yet: it's easier to figure them

out through their interaction than explaining them one at a time.

<ul>

<li><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>

: <code>internet/protocol.py</code></li>

<li><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>

: <code>spread/pb.py</code></li>

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

: <code>spread/pb.py</code></li>

</ul>

Other classes that are involved at some point:

<ul>

<li> <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>

: <code>spread/pb.py</code> </li>

: <code>spread/pb.py</code>, actually defined as

<code>twisted.spread.flavors.Root</code>

in <code>spread/flavors.py</code> </li>

<li> <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>

: <code>spread/pb.py</code>, actually defined as

<code>twisted.spread.flavors.Referenceable</code>

in <code>spread/flavors.py</code> </li>

</ul>

Classes and interfaces that get involved when you start to care

about authorization and security:

<ul>

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.Portal.html" title="twisted.cred.portal.Portal">Portal</a></code>

: <code>cred/portal.py</code></li>

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.IRealm.html" title="twisted.cred.portal.IRealm">IRealm</a></code>

: <code>cred/portal.py</code></li>

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

: <code>spread/pb.py</code>, which you will usually be interacting

with via pb.Avatar (a basic implementor of the interface).</li>

100

</ul>

101

102

<h3>Subclassing and Implementing<a name="auto2"/></h3>

103

104

Technically you can subclass anything you want, but technically you

105

could also write a whole new framework, which would just waste a lot

106

of time. Knowing which classes are useful to subclass or which

107

interfaces to implement is one of the bits of knowledge that's crucial

108

to using PB (and all of Twisted) successfully. Here are some hints to

109

get started:

110

111

<ul>

112

113

<li><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>, <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>: you'll

114

subclass these to make remotely-referenceable objects (i.e., objects

115

which you can call methods on remotely) using PB. You don't need to

116

change any of the existing behavior, just inherit all of it and add

117

the remotely-accessible methods that you want to export.</li>

118

119

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Avatar.html" title="twisted.spread.pb.Avatar">pb.Avatar</a></code>: You'll

120

be subclassing this when you get into PB programming with

121

authorization. This is an implementor of IPerspective.</li>

122

123

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.checkers.ICredentialsChecker.html" title="twisted.cred.checkers.ICredentialsChecker">ICredentialsChecker</a></code>: Implement this if

124

you want to authenticate your users against some sort of data store:

125

i.e., an LDAP database, an RDBMS, etc. There are already a few

126

implementations of this for various back-ends in

127

twisted.cred.checkers.</li>

128

129

</ul>

130

131

132

133

<h2>Things you can Call Remotely<a name="auto3"/></h2>

134

135

At this writing, there are three <q>flavors</q> of objects that can

136

be accessed remotely through <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> objects. Each of these

137

flavors has a rule for how the <code class="python">callRemote</code>

138

message is transformed into a local method call on the server. In

139

order to use one of these <q>flavors</q>, subclass them and name your

140

published methods with the appropriate prefix.

141

142

<ul>

143

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

144

145

This is the first interface we deal with. It is a <q>perspective</q>

146

onto your PB application. Perspectives are slightly special because

147

they are usually the first object that a given user can access in

148

your application (after they log on). A user should only receive a

149

reference to their own perspective. PB works hard to

150

verify, as best it can, that any method that can be called on a

151

perspective directly is being called on behalf of the user who is

152

represented by that perspective. (Services with unusual

153

requirements for <q>on behalf of</q>, such as simulations with the

154

ability to posess another player's avatar, are accomplished by

155

providing indirected access to another user's perspective.)

156

157

158

159

Perspectives are not usually serialized as remote references, so

160

do not return an IPerspective-implementor directly.

161

162

The way most people will want to implement IPerspective is by

163

subclassing pb.Avatar. Remotely accessible methods on pb.Avatar

164

instances are named with the <code class="python">perspective_</code> prefix.

165

166

</li>

167

168

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

169

170

Referenceable objects are the simplest kind of PB object. You can call

171

methods on them and return them from methods to provide access to other

172

objects' methods.

173

174

However, when a method is called on a Referenceable, it's not possible to

175

tell who called it.

176

177

Remotely accessible methods on Referenceables are named with the

178

<code class="python">remote_</code> prefix.

179

180

</li>

181

182

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

183

184

Viewable objects are remotely referenceable objects which have the

185

additional requirement that it must be possible to tell who is calling them.

186

The argument list to a Viewable's remote methods is modified in order to

187

include the Perspective representing the calling user.

188

189

Remotely accessible methods on Viewables are named with the

190

<code class="python">view_</code> prefix.

191

192

</li>

193

194

</ul>

195

196

197

198

<h2>Things you can Copy Remotely<a name="auto4"/></h2>

199

200

In addition to returning objects that you can call remote methods on, you

201

can return structured copies of local objects.

202

203

There are 2 basic flavors that allow for copying objects remotely. Again,

204

you can use these by subclassing them. In order to specify what state you want

205

to have copied when these are serialized, you can either use the Python default

206

<code class="python">__getstate__</code> or specialized method calls for that

207

flavor.

208

209

210

<ul>

211

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

212

213

This is the simpler kind of object that can be copied. Every time this

214

object is returned from a method or passed as an argument, it is serialized

215

and unserialized.

216

217

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

218

provides a method you can override, <code class="py-prototype">getStateToCopyFor(perspective)</code>, which

219

allows you to decide what an object will look like for the

220

perspective who is requesting it. The <code class="python">perspective</code> argument will be the perspective

221

which is either passing an argument or returning a result an

222

instance of your Copyable class.

223

224

For security reasons, in order to allow a particular Copyable class to

225

actually be copied, you must declare a <code class="python">RemoteCopy</code>

226

handler for

227

that Copyable subclass. The easiest way to do this is to declare both in the

228

same module, like so:

229

230

<pre class="python">1

231

232

233

234

235

236

from twisted.spread import flavors

237

class Foo(flavors.Copyable):

238

pass

239

class RemoteFoo(flavors.RemoteCopy):

240

pass

241

flavors.setUnjellyableForClass(Foo, RemoteFoo)

242

</pre>

243

244

In this case, each time a Foo is copied between peers, a RemoteFoo will be

245

instantiated and populated with the Foo's state. If you do not do this, PB

246

will complain that there have been security violations, and it may close the

247

connection.

248

249

250

</li>

251

252

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

253

254

Let me preface this with a warning: Cacheable may be hard to understand.

255

The motivation for it may be unclear if you don't have some experience with

256

real-world applications that use remote method calling of some kind. Once

257

you understand why you need it, what it does will likely seem simple and

258

obvious, but if you get confused by this, forget about it and come back

259

later. It's possible to use PB without understanding Cacheable at all.

260

261

262

Cacheable is a flavor which is designed to be copied only when necessary,

263

and updated on the fly as changes are made to it. When passed as an argument

264

or a return value, if a Cacheable exists on the side of the connection it is

265

being copied to, it will be referred to by ID and not copied.

266

267

Cacheable is designed to minimize errors involved in replicating an object

268

between multiple servers, especially those related to having stale

269

information. In order to do this, Cacheable automatically registers

270

observers and queries state atomically, together. You can override the

271

method <code class="py-prototype">getStateToCacheAndObserveFor(self,

272

perspective, observer)</code> in order to specify how your observers will be

273

stored and updated.

274

275

276

Similar to

277

<code class="python">getStateToCopyFor</code>,

278

<code class="python">getStateToCacheAndObserveFor</code> gets passed a

279

perspective. It also gets passed an

280

<code class="python">observer</code>, which is a remote reference to a

281

<q>secret</q> fourth referenceable flavor:

282

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

283

284

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

285

the object that represents your

286

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

287

of the connection. It is registered using the same method as

288

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

289

RemoteCache is different, however, in that it will be referenced by its peer.

290

It acts as a Referenceable, where all methods prefixed with

291

<code class="python">observe_</code> will be callable remotely. It is

292

recommended that your object maintain a list (note: library support for this

293

is forthcoming!) of observers, and update them using

294

<code class="python">callRemote</code> when the Cacheable changes in a way

295

that should be noticeable to its clients.

296

297

Finally, when all references to a

298

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

299

perspective are lost,

300

<code class="py-prototype">stoppedObserving(perspective, observer)</code>

301

will be called on the

302

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

303

perspective/observer pair that <code>getStateToCacheAndObserveFor</code> was

304

originally called with. Any cleanup remote calls can be made there, as well

305

as removing the observer object from any lists which it was previously in.

306

Any further calls to this observer object will be invalid.

307

</li>

308

</ul>

309

310

311

<h2>Footnotes</h2><ol><li><a name="footnote-1">Most of Twisted is like this. Hell, most of

312

unix is like this: if you think it would be useful, someone else has

313

probably thought that way in the past, and acted on it, and you can take

314

advantage of the tool they created to solve the same problem you're facing

315

now.</a></li></ol></div>

316

317

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

318

Version: 10.0.0

319

</body>

320

</html>

b'\\ No newline at end of file'

Older »