tobytcpThis package contains the tobytcp::TobyMessenger struct that provides the ability to asynchronously talk TobyTcp over a TcpStream.
TobyTcp is a protocol that allows for the use of a raw tcp stream for communicating messages, bi-directionally. See below for more details.
NOTE: No tests! It works, but not tests...
To use a TobyMessenger to send messages over a TcpStream, you first create a new TobyMessenger, then start() it to get a Sender and Receiver that will take care of encoding the data, and sending it over the TcpStream asynchronously!
```rust extern crate tobytcp;
use std::net::TcpStream; use tobytcp::TobyMessenger;
...
let stream = TcpStream::connect("127.0.0.1:34254").unwrap(); let tobymessenger = TobyMessenger::new(stream); let (sender, receiver) = tobymessenger.start();
// Send a 'Hello!' sender.send("Hello!".asbytes().tovec()).unwrap();
// Receive a message! let recv_buf = receiver.recv().unwrap(); ```
This library is threadsafe. You can .clone() the Sender object to have multiple threads all send data through the stream, and the TobyMessenger will send them individually. The Receiver can only be owned by one thread, and there is no .clone() so you can only have one consumer.
Note: The underlying queue mechanism is a MultipleProducersSingleConsumer queue, check out its documentation!
The TobyTcp protocol uses length prefixing for message framing.
Messages must be prefixed by eight (8) bytes, for a total of 64 bits. This 8 byte/64 bit segment of every message must contain the number of bytes present in the message being sent (NOT including the 8 bytes used for describing the size). The length prefix must be little-endian.
You can use the protocol module to encode data into TobyTcp format. No other helpers are there at this time but can be added
let toby_message = protocol::encode_tobytcp(my_data);
Here is an example of an ecnoded messages. The message has 18 bytes of data, and in the end, 18 + 8 = 26 bytes are sent, with the first 8 bytes representing the length.
00 00 00 00 00 00 00 12 74 6f 62 79 20 69 73 20 61 20 67 6f 6f 64 20 64 6f 67
This little library has not been heavily tested, and I would avoid using it in a 'production' environment. This has just been a rust and tcp learning experience for me, and it is used in a tiny project I'm working on.
Also I don't think it works on 32 bit machines..
In no particular order:
- 32 bit machines might work, but probably not if the data is over u32::max
- It prints to stderr when something breaks, which is kind of ugly
- It doesn't hang up TcpStreams properly, it just kind of stops working if the stream is broken
- Uses experimental try_from
The University of Illinois/NCSA (National Center for Supercomputing Applications) Open Source License
See LICENSE file. This a permissive open source license similar to Apache-2.0.