[WIP] Add first draft of packet queue FSM

Add first draft of packet queue finite-state-machine definition.  See
`packet_queue_fsm.pdf` output from running `scons` in the `nadamq/src`
directory.

Each transitional event is represented by a single character, as defined
in the packet_queue_fsm.rl file.

TODO
====

Create an event queue structure and modify the Ragel actions to push the
appropriate events onto the event queue to perform state transitions.
For example, upon successful parsing of a complete `DATA` packet, a `D`
should be push onto the event queue to trigger a transition from the
`ProcessPacket` state to the `ProcessData` state.  Note that this can be
done from within the `handle_data` action.
[WIP] Add initial PacketSocket draft

Add initial draft of `PacketSocket` class, which processes events
related to sending, receiving, and validating packets on an interface.

Add `dump_events_header.py` script to extract the labels of events
defined in a Ragel state-chart.  The script can be used to generate the
`PacketSocketEvents.h` header based on the `packet_socket_fsm.rl` file
to provide a reverse mapping from each event character to the
label for the corresponding event.
Add CircularBuffer class written by Mahir Atmis

Add CircularBuffer class written by [Mahir Atmis][1].

[1]: http://atmismahir.blogspot.com.tr/2014/03/generic-circular-buffer.html
Add `isFull` method to CircularBuffer class
[WIP] Start adding PacketSocket event handling
Add StreamPacketSocket, StreamPacketParser member
[WIP] Add preliminary support for cloning packet
Add double-ended queue class...

Add double-ended queue class.  The double-ended queue can easily be used
to implement a "first-in first-out" _(i.e., FIFO)_ buffer.

See `test_deque.cpp` for example usage.
Add fixed-size buffer allocator class...

Add fixed-size buffer allocator class.  This could be useful, e.g., for
allocating a fixed size pool of packet buffers that can be easily freed
and reused.
Add PacketAllocator, restructure build layout

Add `PacketAllocator` to allocate packets, provided an `Allocator` type,
where the `Allocator` implements the following interface:

 - `uint_8 *alloc()`: Allocate a buffer.
 - `void free(uint_8 *)`: Free a buffer that was allocated by `alloc()`.

__NB__ Currently, only fixed size buffers of a pre-defined size may be
created, as there is no argument to the `alloc` function to specify the
size of the buffer.  The default `Allocator` type for the
`PacketAllocator` is the `FixedSizeBufferPool`, which allocates buffers
of a fixed size, where the size is defined at compile-time.

Restructure build layout to build all binaries in a `build` directory in
the root of the repository.

Notes
=====

TODO - We could probably add a size argument to the `Allocator::alloc`
method.  In the case of the `FixedSizeBufferPool`, we would just return
a `NULL` pointer if the requested buffer size was too large.  Otherwise,
we would just return a fixed-size buffer, which would be at least as
large as the requested size.  This would lead to wasted memory in some
cases, but should be sufficient for our use case and will keep the
interface general enough to support allocators applicable to
environments that are not memory-constrained.
Modify StreamPacketSocket to use PacketAllocator

Modify `StreamPacketSocket` to use `PacketAllocator` to manage packet
buffers.

Packet buffer lifetime
======================

The following describes the current lifetime of a packet buffer:

 1. Upon creation of a `StreamPacketSocket`, the packet parser is
   assigned a packet with a buffer of default size allocated from the
   `PacketAllocator`.
 2. When a full packet has been parsed by the packet parser, the
  `StreamPacketSocket` pushes the full packet onto the receiving queue
  and allocates a new packet for the packet parser.
 3. Once a packet has been handled, the buffer of the packet is freed.

TODO
====

While the socket is currently responsible for both allocation and
deallocation of the buffer for each packet, it might be beneficial to
delegate deallocation.

For example, consider the case where we have some type of packet stream
interface, which queues up packets and exposes a `read_byte` interface
to consume bytes from packets as an encapsulated byte stream.

    Receive packet `P1`
                ____________
    --->P1---> |         P1 |
               --------------

    Receive packet `P2`
                ____________
    --->P2---> |      P2,P1 |
               --------------

    Receive packet `P3`
                ____________
    --->P3---> |   P3,P2,P1 |
               --------------

                                Read byte(s) from packet `P1`
                                asynchronously.
                ____________
               |   P3,P2,P1 | ---->
               --------------

                                Packet `P1` empty, so deallocate packet
                                buffer and pop `P1` from queue.
                ____________
               |      P3,P2 |
               --------------
                           |
                           \--> P1 (deallocate buffer)

    Receive packet `P4`
                ____________
    --->P4---> |   P4,P3,P2 |
               --------------
[NB] Add PacketStream (see previous commit)
Deallocate empty packet after reading last byte...

Deallocate empty packet from packet stream after reading last payload
byte from packet.  Prior to this commit, deallocation of empty packets
at the tail of the packet stream queue only occurred upon the _next_
read operation.
Dump byte counts after queueing packets
Enable socket use with a buffer pool size of 1...

Enable socket use with a payload buffer pool size of one.  To accomplish
this, we only allocate new payload buffer for the parser to use when the
next byte is available on the input stream.  Prior to this commit, the
parser held a packet payload buffer, which meant that the parser always
tied up a buffer, even when no new data was ready to be parsed.

As of this commit, the packet parser passes ownership of the payload
buffer from a successfully parsed data packet to the receiving packet of
the socket. If the parser's packet has no buffer allocated and there is
no buffer left in the allocation pool, no data will be read from the
input stream. However, as long as data is available on the input stream,
buffer allocation will be retried until a buffer becomes available in
the allocation pool.  This allows parsing to resume once a buffer has
been released at some point down the processing line.
Queue `ACK` after receipt of data packet,...

Queue `ACK` after receipt of data packet.

Fake the sending of packets in the transmission queue.

__NB__ There is currently no handling being done to check `ACK` messages
match the most recently sent data packet before sending the next queued
packet.
Add write_packet function, with test_packet_writer

Add `write_packet` function to write a packet to any stream object
providing a `write(const char *data, size_t len)` method.

A `test_packet_writer` program, which writes a packet to a file based on
the provided command-line arguments.

Notes
=====

Perhaps `test_packet_writer` should be allow appending as well.
Add `tostring` method to Cython cPacket API

Add `tostring` method to Cython `cPacket` API, which uses the
`write_packet` `C++` function to serialize the packet to a
`std::stringstream`.

__NB__ The `tostring` method will deprecate the `create*bytes` API
functions.
[NB] Add kwargs to set packet attrs in ctor...

Add keyword arguments to set attributes of `cPacket` instance in
constructor _(i.e., in `cPacket.__cinit__`).

Add test-cases for `cPacket`, including the following cases:

 * Default packet allocation, i.e., no iuid, type, or data/buffer.
 * No buffer allocation.
 * Auto-buffer based on data content.
 * Setting allocating buffer without setting data contents.
 * Setting data while allocating larger buffer.
Enforce max buffer-size from `buffer_size_` dtype