diff options
author | Victor Shepelev <zverok.offline@gmail.com> | 2022-12-24 00:48:58 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-12-24 11:48:58 +1300 |
commit | c3c116f6a6b92d0224b35e7423959a7ab39ddc6b (patch) | |
tree | ca2dc80b919a87835a6abdb1f1630d9c3f0ff7a7 | |
parent | 11ad9a42d76ba785b2ec93f327469ead9b810ef4 (diff) | |
download | ruby-c3c116f6a6b92d0224b35e7423959a7ab39ddc6b.tar.gz |
[DOC] Document new methods of IO::Buffer and Fiber::Scheduler (#7016)
Co-authored-by: Samuel Williams <samuel.williams@oriontransfer.co.nz>
-rw-r--r-- | io_buffer.c | 79 | ||||
-rw-r--r-- | scheduler.c | 18 |
2 files changed, 87 insertions, 10 deletions
diff --git a/io_buffer.c b/io_buffer.c index d866c967b7..c5f0b193c3 100644 --- a/io_buffer.c +++ b/io_buffer.c @@ -2415,10 +2415,10 @@ rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset) } /* - * call-seq: read(io, [length, [offset]]) -> self + * call-seq: read(io, [length, [offset]]) -> read length or -errno * * Read at most +length+ bytes from +io+ into the buffer, starting at - * +offset+. + * +offset+. If an error occurs, return <tt>-errno</tt>. * * If +length+ is not given, read until the end of the buffer. * @@ -2428,14 +2428,17 @@ rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset) * * Example: * - * buffer = IO::Buffer.for('test') - * # => - * # <IO::Buffer 0x00007fca40087c38+4 SLICE> - * # 0x00000000 74 65 73 74 test - * buffer.read(File.open('/dev/urandom', 'rb'), 4) - * # => - * # <IO::Buffer 0x00007fca40087c38+4 SLICE> - * # 0x00000000 2a 0e 0e 0e *... + * IO::Buffer.for('test') do |buffer| + * p buffer + * # => + * # <IO::Buffer 0x00007fca40087c38+4 SLICE> + * # 0x00000000 74 65 73 74 test + * buffer.read(File.open('/dev/urandom', 'rb'), 2) + * p buffer + * # => + * # <IO::Buffer 0x00007f3bc65f2a58+4 EXTERNAL SLICE> + * # 0x00000000 05 35 73 74 .5st + * end */ static VALUE io_buffer_read(int argc, VALUE *argv, VALUE self) @@ -2536,6 +2539,32 @@ rb_io_buffer_pread(VALUE self, VALUE io, rb_off_t from, size_t length, size_t of return rb_thread_io_blocking_region(io_buffer_pread_internal, &argument, descriptor); } +/* + * call-seq: pread(io, from, length, [offset]) -> read length or -errno + * + * Read at most +length+ bytes from +io+ into the buffer, starting at + * +from+, and put it in buffer starting from specified +offset+. + * If an error occurs, return <tt>-errno</tt>. + * + * If +offset+ is not given, put it at the beginning of the buffer. + * + * Example: + * + * IO::Buffer.for('test') do |buffer| + * p buffer + * # => + * # <IO::Buffer 0x00007fca40087c38+4 SLICE> + * # 0x00000000 74 65 73 74 test + * + * # take 2 bytes from the beginning of urandom, + * # put them in buffer starting from position 2 + * buffer.pread(File.open('/dev/urandom', 'rb'), 0, 2, 2) + * p buffer + * # => + * # <IO::Buffer 0x00007f3bc65f2a58+4 EXTERNAL SLICE> + * # 0x00000000 05 35 73 74 te.5 + * end + */ static VALUE io_buffer_pread(int argc, VALUE *argv, VALUE self) { @@ -2610,6 +2639,20 @@ rb_io_buffer_write(VALUE self, VALUE io, size_t length, size_t offset) return rb_thread_io_blocking_region(io_buffer_write_internal, &argument, descriptor); } +/* + * call-seq: write(io, length, [offset]) -> written length or -errno + * + * Writes +length+ bytes from buffer into +io+, starting at + * +offset+ in the buffer. If an error occurs, return <tt>-errno</tt>. + * + * If +offset+ is not given, the bytes are taken from the beginning + * of the buffer. + * + * out = File.open('output.txt', 'wb') + * IO::Buffer.for('1234567').write(out, 3) + * + * This leads to +123+ being written into <tt>output.txt</tt> + */ static VALUE io_buffer_write(int argc, VALUE *argv, VALUE self) { @@ -2709,6 +2752,22 @@ rb_io_buffer_pwrite(VALUE self, VALUE io, rb_off_t from, size_t length, size_t o return rb_thread_io_blocking_region(io_buffer_pwrite_internal, &argument, descriptor); } +/* + * call-seq: pwrite(io, from, length, [offset]) -> written length or -errno + * + * Writes +length+ bytes from buffer into +io+, starting at + * +offset+ in the buffer. If an error occurs, return <tt>-errno</tt>. + * + * If +offset+ is not given, the bytes are taken from the beginning of the + * buffer. If the +offset+ is given and is beyond the end of the file, the + * gap will be filled with null (0 value) bytes. + * + * out = File.open('output.txt', File::RDWR) # open for read/write, no truncation + * IO::Buffer.for('1234567').pwrite(out, 2, 3, 1) + * + * This leads to +234+ (3 bytes, starting from position 1) being written into + * <tt>output.txt</tt>, starting from file position 2. + */ static VALUE io_buffer_pwrite(int argc, VALUE *argv, VALUE self) { diff --git a/scheduler.c b/scheduler.c index 9f28ae0eb6..fb84e6b4dd 100644 --- a/scheduler.c +++ b/scheduler.c @@ -118,6 +118,9 @@ Init_Fiber_Scheduler(void) rb_define_method(rb_cFiberScheduler, "io_wait", rb_fiber_scheduler_io_wait, 3); rb_define_method(rb_cFiberScheduler, "io_read", rb_fiber_scheduler_io_read, 4); rb_define_method(rb_cFiberScheduler, "io_write", rb_fiber_scheduler_io_write, 4); + rb_define_method(rb_cFiberScheduler, "io_pread", rb_fiber_scheduler_io_pread, 5); + rb_define_method(rb_cFiberScheduler, "io_pwrite", rb_fiber_scheduler_io_pwrite, 5); + rb_define_method(rb_cFiberScheduler, "io_select", rb_fiber_scheduler_io_select, 4); rb_define_method(rb_cFiberScheduler, "kernel_sleep", rb_fiber_scheduler_kernel_sleep, 1); rb_define_method(rb_cFiberScheduler, "address_resolve", rb_fiber_scheduler_address_resolve, 1); rb_define_method(rb_cFiberScheduler, "timeout_after", rb_fiber_scheduler_timeout_after, 3); @@ -490,6 +493,14 @@ rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t lengt return rb_check_funcall(scheduler, id_io_read, 4, arguments); } + +/* + * Document-method: Fiber::Scheduler#io_read + * call-seq: io_pread(io, buffer, from, length, offset) -> read length or -errno + * + * Invoked by IO::Buffer#pread. See that method for description of arguments. + * + */ VALUE rb_fiber_scheduler_io_pread(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset) { @@ -537,6 +548,13 @@ rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t leng return rb_check_funcall(scheduler, id_io_write, 4, arguments); } +/* + * Document-method: Fiber::Scheduler#io_pwrite + * call-seq: io_pwrite(io, buffer, from, length, offset) -> written length or -errno + * + * Invoked by IO::Buffer#pwrite. See that method for description of arguments. + * + */ VALUE rb_fiber_scheduler_io_pwrite(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset) { |