Class: Arpie::Protocol

Inherits:
Object
  • Object
show all
Includes:
Arpie
Defined in:
lib/arpie/protocol.rb

Overview

A Protocol converts messages (which are arbitary objects) to a suitable on-the-wire format, and back.

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

MTU

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Arpie

#bogon!, #incomplete!

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
  @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.

Raises:



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.

Raises:

  • (NotImplementedError) 


265
266
267
 
# File 'lib/arpie/protocol.rb', line 265

def assemble binaries, meta
  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

Raises:



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, meta = {} # :yields: binaries, metadata
  @stowbuffer ||= {}
  @stowbuffer[token] ||= []
  @stowbuffer[token] << binary

  @metabuffer ||= {}
  @metabuffer[token] ||= {}
  @metabuffer[token].merge!(meta)

  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.

Yields:

  • (binary) 


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.

Yields:

  • (obj) 


191
192
193
 
# File 'lib/arpie/protocol.rb', line 191

def to obj
  yield obj
end