Naming future objects and their methods

[Stefan Schwarzer]

Hello,

I wrote a `Connection` class that can be found at [1]. A
`Connection` object has a method `put_bytes(data)` which
returns a "future" [2]. The data will be sent asynchronously
by a thread attached to the connection object.

The future object returned by `put_bytes` has a `was_sent`
method which will return `True` once the sender thread has
actually sent the data via a socket call. An example might
look like

put_result = connection.put_bytes(data)
if put_result.was_sent(timeout=1.0):
print "Data has been sent."
else:
print "Data hasn't been sent within one second."

However, I'm not comfortable with the combination of the
names of the future and its method. After all, not the
`put_result` was sent, but the data that was the argument in
the `put_bytes` call. Maybe `data_was_sent` is better than
`was_sent`, but `put_result.data_was_sent()` doesn't feel
right either.

What do you think would be a "natural" way to name the
future returned by `put_bytes` and possibly the `was_sent`
method attached to it? Can you even come up with nice naming
rules for futures and their methods?

I tried to find suggestions by using a search engine and
StackOverflow, but wasn't successful. PEP 3148 [3] describes
an API, but it's quite abstract (`Executor.submit`,
`Future.result` etc.).

[1] https://bitbucket.org/sschwarzer/connection/src/f705e612f764/connection.py
[2] http://en.wikipedia.org/wiki/Future_(programming)
[3] http://www.python.org/dev/peps/pep-3148/

Stefan

 

[Laurent Pointal]

Hello,

I wrote a `Connection` class that can be found at [1]. A
`Connection` object has a method `put_bytes(data)` which
returns a "future" [2]. The data will be sent asynchronously
by a thread attached to the connection object.

The future object returned by `put_bytes` has a `was_sent`
method which will return `True` once the sender thread has
actually sent the data via a socket call. An example might
look like

put_result = connection.put_bytes(data)
if put_result.was_sent(timeout=1.0):
print "Data has been sent."
else:
print "Data hasn't been sent within one second."

However, I'm not comfortable with the combination of the
names of the future and its method. After all, not the
`put_result` was sent, but the data that was the argument in
the `put_bytes` call. Maybe `data_was_sent` is better than
`was_sent`, but `put_result.data_was_sent()` doesn't feel
right either.

<zip>

Just an idea:
put_result ==> dataput
was_sent ==> sent

dataput = connection.put_bytes(data)
if dataput.sent(timeout=1.0):
print "Data has been sent."
else:
print "Data hasn't been sent within one second."

 

[Stefan Schwarzer]

Hello,

Here's a summary of the messages which reached me in this
newsgroup and by e-mail. They are ordered by the time they
reached me at.

(According to the headers, each of the answers went to
either comp.lang.python or (e-mail address removed) . I
thought there was some kind of gateway, but in my reader I
only saw one answer in the newsgroup.)

I wrote a `Connection` class that can be found at [1]. A
`Connection` object has a method `put_bytes(data)` which
returns a "future" [2]. The data will be sent asynchronously
by a thread attached to the connection object.

The future object returned by `put_bytes` has a `was_sent`
method which will return `True` once the sender thread has
actually sent the data via a socket call. An example might
look like

put_result = connection.put_bytes(data)
if put_result.was_sent(timeout=1.0):
print "Data has been sent."
else:
print "Data hasn't been sent within one second."

However, I'm not comfortable with the combination of the
names of the future and its method. After all, not the
`put_result` was sent, but the data that was the argument in
the `put_bytes` call. Maybe `data_was_sent` is better than
`was_sent`, but `put_result.data_was_sent()` doesn't feel
right either.

1) Just name the future (`put_result` in my example)
`future`. Register a callback function instead of asking
the object returned by `put_bytes` for the result.

2) Rename `put_result` to `dataput` and `was_sent` to `sent`:

dataput = connection.put_bytes(data)
if dataput.sent(timeout=1.0):
print "Data has been sent."
else:
print "Data hasn't been sent within one second."

In my opinion, this gives a nice API (I'd spell `dataput`
`data_put` though).

3) Similar to (2), but rename `dataput` to `packet`, so we get:

packet = connection.put_bytes(data)
if packet.sent(timeout=1.0):
print "Data has been sent."
else:
print "Data hasn't been sent within one second."

4) Use variable names according to the goal/content of the
values instead of their datatype.

(`put_result` is somewhere in between; it's not named
after the type `SendFuture`, but as I used a rather
generic example, the purpose of the value isn't known,
apart from that it was some "handle" to get the actual
result from.)

I guess I'll go with (2). I like suggestion (3), too.
However, although in my opinion it's a nice name to read in
this context, it may put readers on the wrong track about
the kind of the data. I think `packet` reads as if this was
the content being sent or some kind of container for it.

Thank you for all the answers!

Stefan