Opened 16 years ago

Closed 15 years ago

#1726 enhancement closed fixed (fixed)

Enhanced docstring for callFromThread

Reported by: Cory Dodt Owned by:
Priority: highest Milestone:
Component: core Keywords:
Cc: Cory Dodt, Jean-Paul Calderone Branch:
Author:

Description

""" [ ... ] and I'm confused every time I see those functions. It's probably too late to change the name, but might I suggest changing the first sentence of callFromThread's docstring from:

Call a function from within another (i.e. non-reactor) thread.

to:

Cause a function to be executed asynchronously on the reactor thread.

"""

It's pretty silly that I have to create a branch to do this, but okay.

Change History (11)

comment:1 Changed 16 years ago by Cory Dodt

Reassigning randomly, per Glyph.

comment:2 Changed 16 years ago by Cory Dodt

Cc: Glyph Cory Dodt added
Keywords: review added

comment:3 Changed 16 years ago by Jean-Paul Calderone

For future reference, you could just attach a patch to the ticket if you want.

comment:4 Changed 16 years ago by Cory Dodt

Cc: dash added

glyph doesn't want it, let's try dash.

comment:5 Changed 16 years ago by Glyph

Cc: Glyph dash removed
Owner: changed from Glyph to dash
Priority: normalhighest

Reassigning rather than ccing

comment:6 Changed 16 years ago by Cory Dodt

BTW branch is docstring-1726.

comment:7 Changed 16 years ago by Glyph

Owner: changed from dash to Cory Dodt

I definitely see the problem with the existing text, but "Cause a function to be executed asynchronously on the reactor thread" could also mean "when running on the reactor thread, cause a function to be executed asynchronously (e.g. in a thread).

The .NET platform uses "asynchronously" to mean run in a thread with a callback you can request in your own thread.

Let's come up with another phrasing...

comment:8 Changed 16 years ago by Cory Dodt

Glyph suggests this instead of the first two paragraphs:

"""From code running within a non-reactor thread (e.g. one created by callInThread), call this method to cause the given function to be invoked at some point in the future by the reactor on the main I/O thread."""

comment:9 Changed 15 years ago by Jean-Paul Calderone

Cc: Jean-Paul Calderone added
Keywords: review removed

What's up with the win32/maintainer-nodes.txt changes in this branch?

The above docstring is inaccurate, so it shouldn't be used. Dropping "asynchronously" from the docstring currently in svn and replacing "on" with "by" seems fine to me.

comment:10 Changed 15 years ago by Cory Dodt

Resolution: fixed
Status: newclosed

(In [17736]) Resolve bug #1726, edit docstring for callFromThread

Fixes #1726

Author: moonfallen

Reviewer: exarkun

Candy: delicious

comment:11 Changed 11 years ago by <automation>

Owner: Cory Dodt deleted
Note: See TracTickets for help on using tickets.