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, VERSION

Instance Method Summary collapse

Methods included from Arpie

#bogon!, #incomplete!

Instance Method Details

#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) 


252
253
254
 
# File 'lib/arpie/protocol.rb', line 252

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:

  • (YieldResult) 


223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/arpie/protocol.rb', line 223

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) 


203
204
205
206
 
# File 'lib/arpie/protocol.rb', line 203

def from binary, &block #:yields: message
  yield binary
  0
end

#to(obj) {|obj| ... } ⇒ Object

Convert obj to on-the-wire format.

Yields:

  • (obj) 


184
185
186
 
# File 'lib/arpie/protocol.rb', line 184

def to obj
  yield obj
end