Slashdot Mirror
Naming Bi-Directional Streams In an API?
DingoTango writes "My coworker and I are designing an infrastructure API to manage data streams. It will allow a client developer to set up streams going to and from some invoked server functionality, and allow a server developer to write services that both consume and produce streaming data. Our quite civil disagreement involves naming: From the perspective of the client platform, the client's output stream goes to the server, and input stream comes from it. For the purpose of any ensuing discussion, let's call this the 'Local' perspective. However, if the client developer considers the service to be a widget, then the stream going to the service is the input stream and the stream coming from it is the output. Let's call this the 'Widget' perspective. As this is an infrastructure utility, we aren't able to name the streams according to function. What say ye, Slashdot? Is there any precedence, experience, or ungrounded yet vociferous opinion that will resolve this for us?"
Use foo and bar. Everyone understands that.
Why not call them the "client to server" stream and the "server to client" stream?
UploadStream: data goes to a server.
DownloadStream: data goes from the server.
The syntax from socket programming, like send, receive, and listen, seems well suited for situations where both sides can act as clients or servers. Both sides would use the same syntax, each naming things from its own perspective.
...I think you want StackOverflow which is a few clicks that way ------>
I would call one of the streams "input" and the other one "send"
Otherwise it just gets too confusing.
I don't therefore I'm not.
...but the SEND/RECEIVE pins between modem and computer are always named from the perspective of the computer. There's precedent to use server-centric nomenclature.
Matthew G P Coe
http://mgpcoe.blogspot.com/
I can definitely the benefit of names pairs such as "Upload"/"Download" or "toServer/toClient" or "toServer/fromServer". Those all work when you've got a clear client/server orientation. But, if you're talking about more distributed situations where you have more of a peer orientation, those break down.
If you can name them separately in the client and in the server, why not use names that are meaningful to the local context? For example, the client's output stream goes to the server's input stream, and vice versa? You've got good precedent for that today in UNIXland with stdin and stdout. Consider a pipe: One side writes to its stdout, and the other side reads it from stdin. Seems perfectly logical to me.
Program Intellivision!
Indeed, upload and download were highly directional and even connotated the initiator. Unfortunately the terms have become corrupted where an upload became synonymous with outgoing data transfer and download with incoming data transfer, and both terms being applied to the same transfer, disregarding the initiator (particularly in torrenting software).
You push a file: you send an upload, the remote machine receives your upload; you pull a file: the remote machine sends you a download, you receive that download. The data stream is either an upload or a download depending on whether it is a push or pull. Either result could be incoming or outgoing to your local machine depending on which machine you're controlling. Thus torrenting is always a download, never an upload. Actual uploading only occurs for services that accept unrequested files like an FTP server that allows you to PUT files.
Uploads and downloads are data streams, not command streams. You would not apply them to a telnet session.
Unless you're NASA. Then uploads are against Earth gravity and downloads are towards Earth gravity regardless of anything else. In future, NASA will have to generalize that to other gravity wells.
I'm going to assume your server accepts all input given it and produces output for all input and there isn't a command and control interface, or at least not at the immediate level.
Here your data streams are I/O with an operation occurring on an external device. We'd call it a peripheral if it weren't over a network. We never call moving data to/from a disk to memory uploading or downloading: that's saving and loading.
If you need to call attention to the network, this would be a reciprocated stream: sending data (not strictly a command) to the server will result in a returning stream of data. If your server exists to serve the requests of the client and initiates no data, you're uploading a stream to the server and receiving its output. The output is a product of your upload, but it is not your upload, nor is it a download; it is the reciprocal response to your upload. It could be a simple as a reflector returning your input to you unprocessed or doing a rot13 on it. Practically a telnet-like service, full duplex.
If you consider the UNIX pipe, it connects the input of one command to the output of another. Something provides the initial input and you will end up with a final output. Whether the client considers its outgoing stream its output locally or the input to the server "widgetally" doesn't matter, as both are correct. What is outgoing from the client is incoming to the server. What's to prevent your client from being another server? Or feeding back between servers?
If you need a term that identifies a stream uniquely regardless of perspective of client or server, you need to define it from an initiator's perspective like upload and download were. But be aware, eventually people will cease to care about the difference. Eventually it will devolve into questions of what is incoming and what is outgoing from their own perspective at a particular node. You might as well call them incoming and outgoing, especially if one's output can become another's input (or even your own).
(Linguistically, is there a difference between incoming/outgoing and ingoing/outcoming? Other than ingo isn't a noun like outgo and income, and outcome isn't a verb? The latter also seem vaguely biological to me.)
Oh, say does that Star-Spangled Banner entwine / The myrtle of Venus with Bacchus's vine?
although "eat me" "drink me" is a close second
Media frameworks such as DirectShow, GStreamer and the such are quite good at this. I work on this specific type of code all day long and maintain my own alternative for extremely high bit-rate environments.
You're talking about designing an object that consumes and produces real-time data. The source of this data is provided by an "upstream" component (or object to be consistent) within your processing pipeline. The destination for the data produced is provided to a "downstream" object.
An API for this type of component should always been seen from the perspective of the user of the component or object. Therefore the interfaces should be named NOT from their internal perspective, but from their external perspective. After all, your APIs are theoretically there so that someone else can use your component without being familiar with the internal architecture of the component itself.
An upstream component which provides data to downstream components are "Data Sources".
A downstream component which consumes data provided by "Data Sources" are "Data Sinks"
A component which acts on data received from an upstream "data source", alters it or produces new data from to send down stream to a "data sink" is called a "transformation" object.
So, a processing pipeline should consist of 3 elements.
1) Data source
2) Transformation Object
3) Data sink
This is similar in nature to :
1) Input
2) Process
3) Output
Though in an object oriented model making use of a pipeline style pattern, it's best to name the objects appropriately.
The output of an object, or the API of an object which provides data to downstream elements, components, objects (etc) should be referred to as Source. So a "Source Object" outputs its data through a "Source". In GStreamer for example, you would say "The source element provides data to downstream elements through one of its source pins" as GStreamer (like other pipeline architectures) provides a uniform interface for providing and consuming data.
The input point of an object (which receives data from upstream objects) should be called a "Sink".
A transformation element contains a minimum of one source and one sink. Data is received by the object via its sink and the processed data is pushed from the object via its source.
This methodology is very simple to use and understand.
An alternative can be "Receiver" which suggests the object received media via this interface and "Transmitter" which suggests that the object transmits data from the interface.
Some people like to use "Listener", "Observer" etc... but since there's no nice corresponding opposite to either of these, I find them grotesque when I encounter them in code.
I think that if you read up on the GStreamer documentation web site, you'll get some great ideas for how best to handle this. Just remember that when you're providing an API to a customer, you're delivering something that should be easy to use and understand from their perspective from the outside. Your API naming should reflect this.
.... Sink and Source?
Think of use cases. What are the clients of your API be doing the most?
What choice will cause the least astonishment to your users?
This is a usability problem. Do what will confuse your user the least. Ask them if you have to.
Write code for both cases against your API. Use it and see what works and what doesn't.
There is no easy answer, this is a design question and aesthetics matter, hence it's rather subjective.
In any case, take into account if your target development platform uses any conventions, and if so stick to them.