Class: Arpie::Protocol
Overview
A Protocol converts messages (which are arbitary objects) to a suitable on-the-wire format, and back.
Direct Known Subclasses
HTTPTestProtocol, MarshalProtocol, SeparatorProtocol, ShellwordsProtocol, SizedProtocol, XMLRPCProtocol, YAMLProtocol, ZlibProtocol
Constant Summary collapse
- CAN_SEPARATE_MESSAGES =
Set this to true in child classes which implement message separation within a stream.
false
Constants included from Arpie
Instance Attribute Summary collapse
-
#metabuffer ⇒ Object
readonly
The meta-information hash used by assemble! No need to touch this, usually.
-
#stowbuffer ⇒ Object
readonly
:stopdoc: The stowbuffer hash used by assemble! No need to touch this, usually.
Instance Method Summary collapse
-
#again! ⇒ Object
Call this within Protocol#from to reparse the current message.
-
#assemble(binaries, meta) ⇒ Object
Called when we’re trying to reassemble a stream of packets.
-
#assemble!(binary, token = :default, meta = {}) ⇒ Object
Stow away a message in this protocols buffer for later reassembly.
-
#from(binary) {|binary| ... } ⇒ Object
Extract message(s) from
binary
. -
#to(obj) {|obj| ... } ⇒ Object
Convert obj to on-the-wire format.
Methods included from Arpie
Instance Attribute Details
#metabuffer ⇒ Object (readonly)
The meta-information hash used by assemble! No need to touch this, usually.
187 188 189 |
# File 'lib/arpie/protocol.rb', line 187 def @metabuffer end |
#stowbuffer ⇒ Object (readonly)
:stopdoc: The stowbuffer hash used by assemble! No need to touch this, usually.
185 186 187 |
# File 'lib/arpie/protocol.rb', line 185 def stowbuffer @stowbuffer end |
Instance Method Details
#again! ⇒ Object
Call this within Protocol#from to reparse the current message.
217 218 219 |
# File 'lib/arpie/protocol.rb', line 217 def again! raise ETryAgain end |
#assemble(binaries, meta) ⇒ Object
Called when we’re trying to reassemble a stream of packets.
Call incomplete! when not enough data is here to reassemble this stream, and yield all results of the reassembled stream.
265 266 267 |
# File 'lib/arpie/protocol.rb', line 265 def assemble binaries, raise NotImplementedError, "Tried to assemble! something, but no assembler defined." end |
#assemble!(binary, token = :default, meta = {}) ⇒ Object
Stow away a message in this protocols buffer for later reassembly. Optional argument: a token if you are planning to reassemble multiple interleaved/fragmented message streams.
If you pass a block, that block will be called; if no block is given, Protocol#assemble will be invoked.
Any leftover binaries passed into assemble! that get not returned in the assembler will be discarded; they are assumed to be syntax or framework.
binary
is the binary packet you want to add to the assembly token
is a object which can be used to identify multiple concurrent assemblies (think Hash.keys) meta
is a hash containing meta-information for this assembly
each call to assemble! will merge these hashes, and pass them
on to Protocol#assemble
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 |
# File 'lib/arpie/protocol.rb', line 236 def assemble! binary, token = :default, = {} # :yields: binaries, metadata @stowbuffer ||= {} @stowbuffer[token] ||= [] @stowbuffer[token] << binary @metabuffer ||= {} @metabuffer[token] ||= {} @metabuffer[token].merge!() assembled = nil if block_given? assembled = yield(@stowbuffer[token], @metabuffer[token]) else # This raises EIncomplete when not enough messages are there, # and passes it straight on to #read_message assembled = assemble(@stowbuffer[token], @metabuffer[token]) end @stowbuffer.delete(token) @metabuffer.delete(token) raise YieldResult, [assembled] end |
#from(binary) {|binary| ... } ⇒ Object
Extract message(s) from binary
.
Yields each message found, with all protocol-specifics stripped.
Should call incomplete
when no message can be read yet.
Must not block by waiting for multiple messages if a message can be yielded directly.
Must not return without calling incomplete
or yielding a message.
Must return the number of bytes these message(s) occupied in the stream, for truncating of the same. Mandatory when CAN_SEPARATE_MESSAGES is true for this class, but ignored otherwise.
210 211 212 213 |
# File 'lib/arpie/protocol.rb', line 210 def from binary, &block #:yields: message yield binary 0 end |
#to(obj) {|obj| ... } ⇒ Object
Convert obj to on-the-wire format.
191 192 193 |
# File 'lib/arpie/protocol.rb', line 191 def to obj yield obj end |