Beta

Slashdot: News for Nerds

×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Naming Bi-Directional Streams In an API?

timothy posted more than 3 years ago | from the will-never-forget-what-me-old-dad-used-to-say dept.

Programming 61

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?"

cancel ×

61 comments

When in doubt (2)

WinstonWolfIT (1550079) | more than 2 years ago | (#35051538)

Use foo and bar. Everyone understands that.

Re:When in doubt (1)

Anonymous Coward | more than 2 years ago | (#35051716)

Just don't cross them.

server-client (3, Insightful)

Anonymous Coward | more than 2 years ago | (#35051542)

Why not call them the "client to server" stream and the "server to client" stream?

Re:server-client (2)

OFnow (1098151) | more than 3 years ago | (#35052880)

The X-windows naming example proves that it's unclear what client and server
really mean!

Re:server-client (1)

mr_mischief (456295) | more than 3 years ago | (#35057830)

Not so much. People are just used to "client" meaning "local", which isn't always the case. In the case of X, the graphics acceleration and rendering are a service provided by one software system to many other software systems, which are your applications. The applications are therefore the clients consuming a service provided by X, which is the server.

There is some minor confusion in that you can use the computing resources of the same system on which X resides to run the applications or you can use the computing resources of a remote system to run the applications and the local system to display them. Still, from the software view, it's the X server servicing the applications. The remote machine(s) might be considered "servers" because you're using their resources remotely, and in fact they are probably SSH servers. You'd use their SSH service to log in and tunnel back to your local X server, but the applications you run on that other system or group of systems are still clients when it comes to using the services of the X server.

Re:server-client (0)

Anonymous Coward | more than 3 years ago | (#35054256)

Just name the stream after whatever it's coming from. This one would be called Anonymous Coward.

no lol (0)

Anonymous Coward | more than 2 years ago | (#35051544)

no lol

Problem solved... (0)

brianwells (809913) | more than 2 years ago | (#35051546)

Name one stream "first" and the other one "post"

Re:Problem solved... (1)

brianwells (809913) | more than 2 years ago | (#35051592)

Or name the first one "not_fast" and the other one "enough"

Already terms in common use for this? (0)

Anonymous Coward | more than 2 years ago | (#35051598)

Why not upstream/downstream or upload/download?

Re:Already terms in common use for this? (0)

Anonymous Coward | more than 2 years ago | (#35051788)

I'm fairly sure this is why we came up with the terms 'upload' and 'download' in the first place. How do you get to be a programmer without running into those terms?

Re:Already terms in common use for this? (2)

HTH NE1 (675604) | more than 3 years ago | (#35052790)

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.)

Direction doesn't matter (1)

Anonymous Coward | more than 2 years ago | (#35051666)

Look at the purpose of the streams. Possible options are "request"/"reply", "control"/"media", etc.

Really Very Simple (0)

Anonymous Coward | more than 2 years ago | (#35051694)

The object that initiates the stream is called a "client" and the object that accepts that stream is the "server". If anyone has trouble with such simple notions then they should be selling used cars and not writing software.

UploadStream and DownloadStream? (3, Interesting)

snikulin (889460) | more than 2 years ago | (#35051714)

UploadStream: data goes to a server.
DownloadStream: data goes from the server.

Re:UploadStream and DownloadStream? (0)

Anonymous Coward | more than 2 years ago | (#35051800)

FTP Put = upload to server from client, Get = download to client from server. ..so this seems to support snikulin's proposal.

Why not just "up" and "down" (0)

Anonymous Coward | more than 3 years ago | (#35059864)

that would be much clearer than "in" and "out" and shorter than "UploadStream" and "DownloadStream"

Upload/Download (0)

Orestesx (629343) | more than 2 years ago | (#35051720)

How about the upload stream and the download stream? Upload and download is usually understood to mean from the client's perspective.

uplink/downlink (0)

Anonymous Coward | more than 2 years ago | (#35051726)

Transmitting to the server is uploading. The direction from the client to the server is the uplink direction.

StreamToServer / StreamToClient (1)

naturaverl (628952) | more than 2 years ago | (#35051758)

Just as described in some of the prior posts, I'd prefer UploadStream and DownloadStream. But if for some reason you don't want to use those names, how about StreamToServer and StreamToClient ?

Ends (1)

SDF_of_BC (921007) | more than 2 years ago | (#35051794)

Look from each component and the input and output streams based on that.
The client's output stream is the server's input stream, the server's output stream is the client's input stream.
The widgets output is the clients input and the widget's input is the clients output.

Re:Ends (2)

Max Littlemore (1001285) | more than 3 years ago | (#35052214)

I would call one of the streams "input" and the other one "send"

Otherwise it just gets too confusing.

socket syntax (3, Insightful)

chaostaco (1233722) | more than 2 years ago | (#35051838)

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.

Excuse me sir, this is a news site... (3, Informative)

NevarMore (248971) | more than 2 years ago | (#35051894)

...I think you want StackOverflow [stackoverflow.com] which is a few clicks that way ------>

Re:Excuse me sir, this is a news site... (3, Insightful)

subreality (157447) | more than 3 years ago | (#35052392)

Not really. Ask Slashdot has always had a little niche for this.

It's a fun question, too. I'd suggest naming them directions that don't correspond to client-server relationships in such an obvious way. So, instead of Up and Down, go for North and South, whichever way feels more appropriate to the situation. In and Out might be a good pair, depending what you want to visualize.

How about Hitherwise and Yonderborne?

Re:Excuse me sir, this is a news site... (1)

snax (160434) | more than 3 years ago | (#35057902)

Thisaway and thataway? Better: deosil and widdershins.

Re:Excuse me sir, this is a news site... (1)

jvonk (315830) | more than 3 years ago | (#35073370)

Better: deosil and widdershins.

I am disgusted by your attempt at Northern Hemisphere cultural imperialism!

Re:Excuse me sir, this is a news site... (1)

tedgyz (515156) | more than 3 years ago | (#35078346)

Ok, you started it:

To and Fro
Ying and Yang
Tweedle-dee and Tweedle-dum

Re:Excuse me sir, this is a news site... (1)

Mashiara (5631) | more than 3 years ago | (#35089470)

how about strange and charmed ?

Use arbitrary names (1)

scurvyj (1158787) | more than 3 years ago | (#35052168)

Use names that don't reflect any meaning, this is usually the safest way.

This applies to any graph where there is no obvious master/slave, server/client, upstream/downstream, initiator/follower relationship, ie. the relationship depends on a momentary viewpoint.

Use 'Ken' and 'Barby' if you like :) Or since you probably have to sell it to morons on higher pay, pick something more conservative. Even colours can work, eg. Red and Green - good enough for Prolog and Quarks! :)

Just as how modems send and receive... (2)

jargonCCNA (531779) | more than 3 years ago | (#35052600)

...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.

Re:Just as how modems send and receive... (0)

Anonymous Coward | more than 3 years ago | (#35063460)

hi, im larry,
can i ask how does it work?

Re:Just as how modems send and receive... (1)

msauve (701917) | more than 3 years ago | (#35066790)

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.

No, they are named from the perspective of the DTE (Data Terminal Equipment). When the RS-232 standard was created, that meant a terminal or a computer. It was "reverse named" from the perspective of a DCE (Data Communications Equipment), which was often a modem.

Mapping that to client/server fails, because both the display terminal (which would probably be considered the client) and the computer (the "server") were DTE, so one could equally well say that there's precedent to use client-centric nomenclature.

Do they have to have the same names on both ends? (2)

Mr Z (6791) | more than 3 years ago | (#35052656)

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.

Re:Do they have to have the same names on both end (1)

gl4ss (559668) | more than 3 years ago | (#35054980)

name them from the perspective from which they're used from the api. that is, functions that take data to be sent elsewhere would be named 'send'(or upload) and 'get','receive' or similar would be the other direction.

but this seems like a case of where they should have just named them john1 and doe3 or _anything_ so they could have moved on with their design, if things go this way then next week they can argue about package names.

Re:Do they have to have the same names on both end (1)

mcmonkey (96054) | more than 3 years ago | (#35058712)

I have 3 questions:

1) Why isn't this the highest modded comment in the thread?

2) Why are others continuing to post after this solution? I mean, why would you do anything other than name the stream coming in to the server as the input stream in the server context, the stream coming from the client as the output stream in the client context, and so on?

3) How long until the entire project crashes in complete disaster? Does it really take 2 developers to figure this out? The only other scenario I can think of is the grown ups are finishing the project while these 2 kids are on a snipe hunt.

Re:Do they have to have the same names on both end (1)

gnapster (1401889) | more than 3 years ago | (#35059344)

Does it really take 2 developers to figure this out?

No, one developer on their own would have figured it out. It takes two developers to make it an issue. ;c)

At first, I didn't understand what all the fuss was about, because I gathered that the server functionality always behaved like a filter. If that is the case, then just treat it like a black box; don't even muddy the waters with the fact that this box is doin' its thing "out" on a server somewhere else. The stream I feed it is 'in', the stream it gives me back is 'out'. No big deal, whether I am developing the client or the server.

But if the client will sometimes send a stream off, expecting nothing in return, then maybe 'in' doesn't make sense? I dunno. It is a convention. People establish conventions so that semantics are predictable, and good conventions align with the user's intuition. If the intuition of users or developers happens to clash, then they ought to just pick something and be done with it, then get accustomed to it. If it moves things along, I am of the crowd that says, "Call one way 'TweedleDum' and the other 'TweedleDee' and get on with your lives."

Words give you power.

I have not used it, but I think that OSCgroups [audiomulch.com] does some related things with passing messages and streams to disparate clients and servers, and if one roots through the codebase it is possible that there might be some interesting conventions there.

MIB solution (0)

Anonymous Coward | more than 3 years ago | (#35052854)

Call them "Bweryang" and "Bob".

car and cdr, obviously (3, Insightful)

decora (1710862) | more than 3 years ago | (#35053020)

although "eat me" "drink me" is a close second

Java syntax (0)

Anonymous Coward | more than 3 years ago | (#35053152)

Why don't you just use Java syntax? An InputStream is input on client and server side, and an OutputStream is the opposite. For what purpose do they need to be named the same on each side?

produce(er) consume(er) (1)

Anonymous Coward | more than 3 years ago | (#35053168)

why not produce(er) and consume(er) as in the messaging world?

How about "From" and "To"? (1)

RealGene (1025017) | more than 3 years ago | (#35053400)

or is that too obvious?

Re:How about "From" and "To"? (0)

Anonymous Coward | more than 3 years ago | (#35057214)

It's not obvious at all! Since both Client and Server send and receive so which is From and which is To depends on perspective.

Make obvious acronyms (KISS principle) (0)

Anonymous Coward | more than 3 years ago | (#35053664)

Try a nice acronym.
from the client's programming perspective:
Client -> Server traffic or c2s (as cts is used in some old modem serial packet stuff)
Client Client s2c
Server - Client sfc

With this scheme, the programmers at either end wont get confused. Just identify who
you are, send, receive.

Flip a coin (0)

Anonymous Coward | more than 3 years ago | (#35054054)

If no one perspective adds more benefit, flip a coin, document and stick to your decision

You should look to media frameworks for this (2)

LostMyBeaver (1226054) | more than 3 years ago | (#35054412)

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.

Re:You should look to media frameworks for this (0)

Anonymous Coward | more than 3 years ago | (#35057420)

There are perfectly good opposites for "Listener" and "Observer"; "Talker" and "Performer" or other synonyms.

However I think your last paragraph says it:
"... you're delivering something that should be easy to use and understand from their perspective from the outside. Your API naming should reflect this."

Cheers!

Everything but the kitchen..... (2)

colin_s_guthrie (929758) | more than 3 years ago | (#35054564)

.... Sink and Source?

Ingress/Egress (0)

Anonymous Coward | more than 3 years ago | (#35054628)

The ingress stream flows in to the network. The egress stream exits the network.

How about simply "stream" and "client"? (1)

D4MO (78537) | more than 3 years ago | (#35055494)

The server just happens to be a well know location for a service that can be connected to. The client initiates the connection. Once the connection is establised the "server" and the "client" effectively become "clients" of each other, when the output of one is plugged into the input of the other.

For example, in .net land (it's where I am, forgive me) you have a TcpListener on the server side. Then when a client connects using a TcpClient, the server creates a corresponding TcpClient on the server side. Writing to the client's TcpClient.Stream will allow you to read from the servers TcpClient.Stream, and vice versa.

Your API should probably be considering the establishment of the connection, rather than the connection itself.

Just do it! (0)

Anonymous Coward | more than 3 years ago | (#35055624)

Pick a convention, stick to it - unless it proves obviously wrong/confusing - and move on....
Just my 2cents.

really? i mean seriously? (1)

hesaigo999ca (786966) | more than 3 years ago | (#35055646)

You guys are setting up a post for a story about naming conventions, when we have so many other news posts that could take precedence.... ...here is one, whatever the providing server's owner decided....as it is they that pay the bills for the server and the in house development, so if they feel like calling the service or widget, porky_pig-IS**my_(FRIEND)....who cares....

What's the most common use (2)

juancn (596002) | more than 3 years ago | (#35056428)

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.

Re:What's the most common use (1)

Shifty0x88 (1732980) | more than 3 years ago | (#35062450)

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.

I agree, the most common usage of your Stream API is where you should derive the names from Also you should think of who will be using this, are they experienced developers?? If so, then they probably just need a clarification of which is which in your documentation, and they should be fine with either version. Just my 2 cents, from a programmers perspective.

Forward and Reverse (0)

Anonymous Coward | more than 3 years ago | (#35056794)

In Wireless, we call the path toward the client the "forward link", and the one from the client the "reverse link". Sounds similar to your situation.

Input is what you put in and output is the result (0)

Anonymous Coward | more than 3 years ago | (#35057074)

It's so simple if you follow this one simple principle: Input is what you put in and output is the result.

I have plans for a really nice bike-shed... (0)

Anonymous Coward | more than 3 years ago | (#35058880)

I just can't decide what color to paint it.

It's arbitrary (1)

Hegh (788050) | more than 3 years ago | (#35059680)

... so just pick one and stick to it.

I'm partial to "input" and "output" myself, from the perspective of the object using them (so a client's output goes to the server's input and vice-versa).

If you need to reference both objects' streams at the same time, you've got "myInput", "myOutput", "hisInput", and "hisOutput" for clarity.

Or just pick something fun; "spinwise" and "widdershins" isn't bad, but may confuse your users.

Simple (1)

jgoemat (565882) | more than 3 years ago | (#35076782)

The InputStream is the one being read from and the OutputStream is the one bing written to. The same stream will be called both depending on which side you're looking at.

Why not do both? (1)

SpaceCracker (939922) | more than 3 years ago | (#35131432)

I think I see your dilemma. If I understand correctly, you are examining the perspective of the client developer that might approach the server in client-server mode, in which case upStream/downStream (or something of that nature) would work nicely. Conversely, the client developer might be working with a widget that appears to him/her as any other client side object. In this case you can use in/out terminology and simply forward the call to the up/down methods respectively. Interesting names could also be ears/mouth, mike/speaker, reader/writer, etc.

Check for New Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Create a Slashdot Account

Loading...