Merge pull request #3305 from Watson1978/io-buffer-state-queries

IO::Buffer: 状態問い合わせの 10 メソッドを追加

Author: znz

manual/api/_builtin/IO__Buffer.md

@@ -10,7 +10,8 @@ include:
 Ruby 3.1 で導入されました。
 
 [c:String] を経由せずにメモリ領域を扱えるため、コピーを避けた入出力
-(zero-copy IO)を実現するために使われます。主に [c:Fiber::Scheduler] の
+(zero-copy IO)を実現するために使われます。主に
+[Fiber::Scheduler](https://docs.ruby-lang.org/en/4.0/Fiber/Scheduler.html) の
 実装のような、低レベルな入出力を扱う場面で利用します。
 
 バッファは以下のいずれかの方法で確保されたメモリ領域を指します。
@@ -78,7 +79,8 @@ OS のページサイズをバイト数で表した値です。
 バッファがロックされていることを表すフラグです。
 
 ロックされている間はバッファの解放やリサイズができません。
-[m:IO::Buffer#locked] を参照してください。
+バッファがロックされているかどうかは [m:IO::Buffer#locked?] で調べられます。
+#@# locked を収録したら、ブロックの間ロックする IO::Buffer#locked への言及も足す
 
 ### const PRIVATE -> Integer
 
@@ -118,7 +120,7 @@ p IO::Buffer::HOST_ENDIAN == IO::Buffer::LITTLE_ENDIAN # => true
 size バイトの、0 で埋められた新しいバッファを作成して返します。
 
 既定では内部(internal)バッファ、すなわち Ruby が直接確保したメモリ領域に
-なります。ただし size が OS 依存の [m:IO::Buffer::PAGE_SIZE] より大きい場合は、
+なります。ただし size が OS 依存の [m:IO::Buffer::PAGE_SIZE] 以上の場合は、
 仮想メモリ機構(Unix では匿名 mmap、Windows では VirtualAlloc)を用いて
 確保されます。flags に [m:IO::Buffer::MAPPED] を指定すると、
 size によらず後者の方法で確保されます。
@@ -299,7 +301,8 @@ p buf.get_string # => "\x00AA\x00"
 変更後の大きさによっては、メモリ領域が別の場所に確保しなおされ、
 内容がそこへコピーされます。
 
-[m:IO::Buffer.for] で作った外部バッファや、ロックされたバッファは大きさを変更できません。
+#@# for を収録したらリンクに戻す
+`IO::Buffer.for` で作った外部バッファや、ロックされたバッファは大きさを変更できません。
 
 - **param** `size` -- 変更後の大きさをバイト数で指定します。
 - **raise** `IO::Buffer::AccessError` -- 大きさを変更できないバッファに対して呼び出した場合に発生します。
@@ -369,3 +372,133 @@ p buf.size  # => 4
 ```
 
 - **SEE** [m:IO::Buffer#transfer], [m:IO::Buffer#null?]
+
+### def empty? -> bool
+
+バッファの大きさが 0 の場合に true を返します。
+
+#@# for を収録したらリンクに戻す
+大きさ 0 のバッファは、[m:IO::Buffer.new] に 0 を渡すか、
+空文字列から `IO::Buffer.for` で作った場合などにできます。
+
+```ruby
+p IO::Buffer.new(0).empty? # => true
+p IO::Buffer.new(4).empty? # => false
+```
+
+### def null? -> bool
+
+バッファがどのメモリ領域も指していない場合に true を返します。
+
+[m:IO::Buffer#free] で解放したバッファ、[m:IO::Buffer#transfer] で所有権を手放した
+バッファ、および最初からメモリ領域を確保していないバッファがこれにあたります。
+
+```ruby
+p IO::Buffer.new(0).null? # => true
+
+buf = IO::Buffer.new(4)
+p buf.null? # => false
+buf.free
+p buf.null? # => true
+```
+
+- **SEE** [m:IO::Buffer#free], [m:IO::Buffer#transfer]
+
+### def valid? -> bool
+
+バッファがアクセス可能な場合に true を返します。
+
+別のバッファや文字列の一部を参照している([m:IO::Buffer#slice] で作った)バッファは、
+参照元が解放されたり別のアドレスに再確保されたりすると、アクセスできなくなります。
+
+### def internal? -> bool
+
+バッファが内部(internal)バッファである場合に true を返します。
+
+内部バッファは、バッファ自身が確保したメモリ領域を参照します。
+文字列などの外部のメモリやファイルのマッピングとは結び付いていません。
+[m:IO::Buffer.new] で作られるバッファは既定で内部バッファです。
+
+```ruby
+p IO::Buffer.new(4).internal? # => true
+```
+
+- **SEE** [m:IO::Buffer#external?]
+
+### def external? -> bool
+
+バッファが外部(external)バッファである場合に true を返します。
+
+外部バッファは、バッファ自身が確保・マップしたのではないメモリ領域を参照します。
+#@# for を収録したらリンクに戻す
+`IO::Buffer.for` で作ったバッファは、文字列のメモリを外部参照します。
+外部バッファは大きさを変更できません。
+
+```ruby
+p IO::Buffer.for("test").external? # => true
+p IO::Buffer.new(4).external?      # => false
+```
+
+- **SEE** [m:IO::Buffer#internal?]
+
+### def readonly? -> bool
+
+バッファが読み取り専用の場合に true を返します。
+
+#@# set_value / for を収録したらリンクに戻す
+読み取り専用のバッファは、`IO::Buffer#set_value` や [m:IO::Buffer#set_string]、
+[m:IO::Buffer#copy] などで変更できません。
+
+`IO::Buffer.for` にブロックを渡さずに作ったバッファは、元の文字列が freeze
+されているかどうかによらず、常に読み取り専用になります。内部で作った文字列の
+複製をバッファの元として使うためです。
+ブロックを渡した場合は元の文字列のメモリを直接参照するため、
+その文字列が freeze されている場合にだけ読み取り専用になります。
+読み取り専用のファイルから作ったバッファも読み取り専用です。
+
+```ruby
+# ブロックを渡さない場合は、元の文字列が freeze されていなくても読み取り専用
+p IO::Buffer.for("test").readonly?                  # => true
+
+# ブロックを渡した場合は元の文字列に従う
+p IO::Buffer.for("test") { |buf| buf.readonly? }    # => false
+p IO::Buffer.for("test".freeze) { |buf| buf.readonly? } # => true
+
+p IO::Buffer.new(4).readonly?                       # => false
+```
+
+### def mapped? -> bool
+
+バッファがマップ(mapped)バッファである場合に true を返します。
+
+マップバッファは、仮想メモリ機構でマップされたメモリ領域を参照します。
+[m:IO::Buffer.new] に [m:IO::Buffer::MAPPED] を指定した場合や、
+大きさが [m:IO::Buffer::PAGE_SIZE] 以上の場合は匿名のマップになります。
+#@# map を収録したらリンクに戻す
+`IO::Buffer.map` で作った場合はファイルに紐づいたマップになります。
+
+### def locked? -> bool
+
+バッファがロックされている場合に true を返します。
+
+ロックされたバッファは大きさの変更や解放ができず、
+さらにロックを取得することもできません。
+システムコールでバッファを使っている間に、そのバッファが移動しないことを
+保証するための仕組みです。
+
+#@since 3.2
+### def shared? -> bool
+
+バッファが共有(shared)バッファである場合に true を返します。
+
+共有バッファは、他のプロセスと共有できるメモリ領域を参照します。
+そのため、このプロセスで変更しなくても内容が変わることがあります。
+#@end
+
+#@since 3.3
+### def private? -> bool
+
+バッファがプライベート(private)バッファである場合に true を返します。
+
+プライベートバッファに加えた変更は、元になったファイルのマッピングには反映されません。
+#@end