RFC: Changes to OSC Block

CinderBlocks
1

Hi all,

Sorry for making so many posts in the last couple of days. Basically, over the last couple of months since OSC’s release a few issues have come up to the API design and I wanted to take care of those things and see what people think.

There are three major changes to the API.

  1. Synchronous functions throw osc::Exception's which wrap the asio::error_code returned from the bind, close and shutdown methods.

  2. Asynchronous functions now take as arguments error handlers and possible complete handlers. Functions such as send and listen, which dispatch their work to the given asio::io_service take functions as arguments. For instance, the send function takes an optional OnErrorFn with the signature void( asio::error_code ) and another optional OnCompleteFn with the signature void(). The errorFn would be called in the case of an error on the send and the completeFn would be called if there was no error. This basically replaces the global handlers and setters that is in the api now.

  3. Finally, and possibly the most controversial change, is the choice to separate the naming scheme between osc::ReceiverUdp and osc::ReceiverTcp of the operation that begins reception at the OS level. For osc::ReceiverUdp, the function’s name is listen. For osc::ReceiverTcp, the function’s name is accept. The differences were chosen to signal the underlying differences in what is actually happening. With listen on the osc::ReceiverUdp side, we’re indiscriminately reading and accepting messages. With accept on the osc::ReceiverTcp side, we’re binding a socket that’s accepting Tcp connections and then firing asynchronous read’s on the newly created sockets. Most of the reason for the change is not only clarity on the operation but also due to the fact that there are different arguments in each signature. The osc::ReceiverUdp::listen signature accepts an OnErrorFn, with signature bool( const asio::error_code &/*error*/, const protocol::endpoint &/*originator*/) that is used by the underlying read function. The osc::ReceiverTcp::accept signature takes an OnAcceptErrorFn, which is called in the case of an acceptor error, and has the signature bool( asio::error_code error ), and OnAcceptFn, which controls the caching of a newly created and connected socket and has the signature bool( TcpSocketRef, uint64_t ). That was a mouthful. There was some discussion about whether this difference was needed. Some believed that it was more important to allow an ease of swap between the two different protocols as far as ci::osc was concerned but my belief is that, because these two protocols are so different that abstracting them would make it very hard to handle and control the underlying complexity.

Anyway, you can see examples and some comments detailing all of the API changes in the SimpleReceiver sample and SimpleSender sample. Definitely would love to hear what people think.

Best,
Ryan

2 Likes
2

Fyi, these changes have been merged into master.

1 Like