Feature #13740: [PATCH] doc/extension.rdoc: start entries for threading and IO

• Status: Closed
• Assignee: -
• Target version: -

[normalperson (Eric Wong)]

Some of it derived from existing documentation in thread.c,
and some of it original. It seems extension.rdoc is getting
large, so maybe it is better broken up into separate manpages
(section "3ruby", maybe?)

Anybody care to review or comment before I commit?
I'll wait a few days, but maybe I'll forget, too.
Anyways no chance of breaking running code (I hope :)

[shevegen (Robert A. Heiler)]

Looks ok to me - at the least I could not spot grammatical errors or typos glancing through it 1-2 times. I have of course no idea about threads themselves really so perhaps someone should also look through who actually knows that stuff too. :)

[normalperson (Eric Wong)]

[e-mail] wrote:

Looks ok to me - at the least I could not spot grammatical
errors or typo glancing through it 1-2 times. I have of course
no idea about threads themselves really so perhaps someone
should also look through who actually knows that stuff too. :)

Thanks for the read, I didn't check the grammar and spelling too
closely :)

I've been dealing with MT for a long time; so there's always a
danger of me leaving critical pieces out by assuming too much
knowledge on the reader's part.

[ko1 (Koichi Sasada)]

void *rb_thread_call_without_gvl(void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2) ::

You need to mention that func is not allowed to call any rb_ functions (there are exceptions but it should be used carefully). IMO this function is to danger so that I recommend to remove an explanation and only reference to the commented document in thread.c. At least, we need to emphasize the danger of this API.

int rb_io_wait_readable(int fd) ::

I'm not expert on this area so this is only a question. Can we support fd on our documented (may it means we encourage to use them) APIs?

[normalperson (Eric Wong)]

[e-mail] wrote:

void *rb_thread_call_without_gvl(void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2) ::

You need to mention that func is not allowed to call any
rb_ functions (there are exceptions but it should be used
carefully). IMO this function is to danger so that I recommend
to remove an explanation and only reference to the commented
document in thread.c. At least, we need to emphasize the
danger of this API.

OK, perhaps I will just refer users to read thread.c since
I mostly reused that text. I will update tomorrow.

Thank you for your response.

int rb_io_wait_readable(int fd) ::

I'm not expert on this area so this is only a question. Can we
support fd on our documented (may it means we encourage to
use them) APIs?

I think there is no choice when it comes to interacting with
3rd-party libraries which open sockets (curl, mysql, pg, ...)
All of those APIs expose FDs for users to integrate into
existing event loop.

• Status changed from Open to Closed

Applied in changeset trunk|r59353.

---

doc/extension.rdoc: start documenting threading and IO APIs

This will hopefully be useful for folks writing C extensions.

• doc/extension.rdoc: start documenting threading and IO APIs
  [ruby-core:82016] [Feature #13740]