Module: Cod

Defined in:
lib/cod.rb,
lib/cod/pipe.rb,
lib/cod/bidir.rb,
lib/cod/iopair.rb,
lib/cod/select.rb,
lib/cod/channel.rb,
lib/cod/process.rb,
lib/cod/service.rb,
lib/cod/callbacks.rb,
lib/cod/tcp_client.rb,
lib/cod/tcp_server.rb,
lib/cod/work_queue.rb,
lib/cod/bidir_server.rb,
lib/cod/select_group.rb,
lib/cod/socket_server.rb,
lib/cod/line_serializer.rb,
lib/cod/simple_serializer.rb,
lib/cod/protocol_buffers_serializer.rb

Overview

The core concept of Cod are ‘channels’. (see Channel::Base) You can create such channels on top of the various transport layers. Once you have such a channel, you #put messages into it and you #get messages out of it. Messages are retrieved in FIFO manner.

channel.put :test1
channel.put :test2
channel.get # => :test1

Cod also brings a few abstractions layered on top of channels: You can use channels to present ‘services’ (Cod::Service) to the network: A service is a simple one or two way RPC call. (one way = asynchronous) 

client = channel.client
client.notify [:foo, :bar]

Cod channels are serializable whereever possible. If you want to tell somebody where to write his answers and/or questions to, send him the channel! This is really powerful and used extensively in constructing the higher order primitives. 

server.put [:some_request, my_channel]
# Server will receive my_channel and be able to contact us there.

All Cod channels have a serializer. If you don’t specify your own serializer, they will use Marshal.dump and Marshal.load. (see SimpleSerializer) This allows to send Ruby objects and not just strings by default. If you want to, you can of course go back to very strict wire formats, see ProtocolBuffersSerializer or LineSerializer for an example of that.

line_protocol_channel = Cod.pipe(Cod::LineSerializer.new)
line_protocol_channel.put 'some_string'

The goal of Cod is that you have to know only very few things about the network (the various transports) to be able to construct complex things. It also translates cryptic OS errors into plain text messages where it can’t just handle them. This should give you a clear place to look at if things go wrong. Note that this can only be ever as good as the sum of situations Cod has been tested in. Contribute your observations and we’ll come up with a way of dealing with most of the tricky stuff!

Types of channels in this version

Cod.pipe

Transports via IO.pipe

Cod.tcp

Transports via TCP (client)

Cod.tcp_server

Transports via TCP (as a server)

Cod.stdio

Connects to $stdin and $stdout (IO.pipe)

Cod.process

Spawn a child process and connects to that process’ $stdin and $stdout (IO.pipe)

Cod.beanstalk

Transports via a tube on beanstalkd

See Also:

Defined Under Namespace

Modules: Beanstalk, Callbacks Classes: Bidir, BidirServer, Channel, ConnectionLost, ExclusiveSection, IOPair, LineSerializer, Pipe, Process, ProtocolBuffersSerializer, ReadOnlyChannel, Select, SelectGroup, Service, SimpleSerializer, SocketServer, TcpClient, TcpServer, WorkQueue, WriteOnlyChannel

Class Method Summary collapse

Class Method Details

.beanstalk(tube_name, server = 'localhost:11300') ⇒ Cod::Beanstalk::Channel

Creates a channel based on the beanstalkd messaging queue.

Parameters:

  • tube_name (String) —

    name of the tube to send messages to / receive messages from

  • server (String) (defaults to: 'localhost:11300') —

    address of the server to connect to

Returns:



129
130
131
 
# File 'lib/cod.rb', line 129

def beanstalk(tube_name, server=nil)
  Cod::Beanstalk::Channel.new(tube_name, server||'localhost:11300')
end

.bidir(serializer = nil) ⇒ Cod::Bidir

Creates a channel based on socketpair (UNIXSocket.pair). This is a IPC-kind of channel that can be used to exchange messages both ways.

Parameters:

  • serializer (#en, #de) (defaults to: nil) —

    optional serializer to use

Returns:



75
76
77
 
# File 'lib/cod.rb', line 75

def bidir(serializer=nil)
  Cod::Bidir.pair(serializer)
end

.bidir_named(name, serializer = nil) ⇒ Object

Creates a named bidirectional channel. Only one end of this will be connected to the unix socket in the file system identified by path.



83
84
85
 
# File 'lib/cod.rb', line 83

def bidir_named(name, serializer=nil)
  Cod::Bidir.named(name, serializer)
end

.bidir_server(name, serializer = nil) ⇒ Object

Creates the server side for a named unix socket connection.



90
91
92
 
# File 'lib/cod.rb', line 90

def bidir_server(name, serializer=nil)
  Cod::BidirServer.new(name, serializer)
end

.pipe(serializer = nil) ⇒ Cod::Pipe

Creates a pipe connection that is visible to this process and its children.

Parameters:

  • serializer (#en, #de) (defaults to: nil) —

    optional serializer to use

Returns:



63
64
65
 
# File 'lib/cod.rb', line 63

def pipe(serializer=nil)
  Cod::Pipe.new(serializer)
end

.process(command, serializer = nil) ⇒ Cod::Process

Runs a command via Process.spawn, then links a channel to the commands stdout and stdin.

Parameters:

  • command (String) —

    command to execute in a subprocess (using Process.spawn)

  • serializer (#en, #de) (defaults to: nil) —

    serializer to use for all messages in channel

Returns:



142
143
144
 
# File 'lib/cod.rb', line 142

def process(command, serializer=nil)
  Cod::Process.new(command, serializer)
end

.select(timeout, groups) ⇒ Hash, ...

A shortcurt for constructing a Select. See Cod::Select#do for more information.

Parameters:

  • timeout (Number) —

    seconds to block before giving up

  • groups —

    channels or io selectors to wait for

Returns:



9
10
11
12
 
# File 'lib/cod/select.rb', line 9

def select(timeout, groups)
  # TODO create an overload without the timeout
  Select.new(timeout, groups).do
end

.stdio(serializer = nil) ⇒ Cod::Pipe

Links a process’ stdin and stdout up with a pipe. This means that the pipes #put method will print to stdout, and the #get method will read from stdin.

Parameters:

  • serializer (#en, #de) (defaults to: nil) —

    optional serializer to use

Returns:



154
155
156
 
# File 'lib/cod.rb', line 154

def stdio(serializer=nil)
  Cod::Pipe.new(serializer, [$stdin, $stdout])
end

.tcp(destination, serializer = nil) ⇒ Cod::TcpClient

Creates a tcp connection to the destination and returns a channel for it.

Parameters:

  • destination (String) —

    an address to connect to, like ‘localhost:1234’

  • serializer (#en, #de) (defaults to: nil) —

    optional serializer to use

Returns:



101
102
103
104
105
 
# File 'lib/cod.rb', line 101

def tcp(destination, serializer=nil)
  Cod::TcpClient.new(
    destination, 
    serializer || SimpleSerializer.new)
end

.tcp_server(bind_to, serializer = nil) ⇒ Cod::TcpServer

Creates a tcp listener on bind_to and returns a channel for it.

Parameters:

  • bind_to (String) —

    an address and port to bind to, in the form “host:port”

  • serializer (#en, #de) (defaults to: nil) —

    optional serializer to use

Returns:



114
115
116
117
118
 
# File 'lib/cod.rb', line 114

def tcp_server(bind_to, serializer=nil)
  Cod::TcpServer.new(
    bind_to, 
    serializer || SimpleSerializer.new)
end