Project

General

Profile

Actions

Feature #13740

closed

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

Added by normalperson (Eric Wong) over 6 years ago. Updated over 6 years ago.

Status:
Closed
Assignee:
-
Target version:
-
[ruby-core:82011]

Description

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


Files

Updated by shevegen (Robert A. Heiler) over 6 years ago

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

Updated by normalperson (Eric Wong) over 6 years ago

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.

Updated by ko1 (Koichi Sasada) over 6 years ago

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?

Updated by normalperson (Eric Wong) over 6 years ago

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.

Actions #5

Updated by Anonymous over 6 years ago

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

Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0