Add deprecations for public `struct rb_io` members. (#7916)

* Add deprecations for public struct rb_io members.

4 files changed, 128 insertions, 12 deletions

diff --git a/ext/objspace/depend b/ext/objspace/depend
index d1e8236eb8..f0e1f928cd 100644
--- a/ext/objspace/depend
+++ b/ext/objspace/depend
@@ -585,6 +585,7 @@ objspace_dump.o: $(top_srcdir)/internal/compilers.h
 objspace_dump.o: $(top_srcdir)/internal/gc.h
 objspace_dump.o: $(top_srcdir)/internal/hash.h
 objspace_dump.o: $(top_srcdir)/internal/imemo.h
+objspace_dump.o: $(top_srcdir)/internal/io.h
 objspace_dump.o: $(top_srcdir)/internal/sanitizers.h
 objspace_dump.o: $(top_srcdir)/internal/serial.h
 objspace_dump.o: $(top_srcdir)/internal/static_assert.h
diff --git a/ext/objspace/objspace_dump.c b/ext/objspace/objspace_dump.c
index d8a11083d6..39584e03b8 100644
--- a/ext/objspace/objspace_dump.c
+++ b/ext/objspace/objspace_dump.c
@@ -18,6 +18,7 @@
 #include "internal/class.h"
 #include "internal/gc.h"
 #include "internal/hash.h"
+#include "internal/io.h"
 #include "internal/string.h"
 #include "internal/sanitizers.h"
 #include "symbol.h"
diff --git a/include/ruby/io.h b/include/ruby/io.h
index 9b381fc9bb..60029fedb6 100644
--- a/include/ruby/io.h
+++ b/include/ruby/io.h
@@ -137,40 +137,50 @@ struct rb_io_encoding {
     VALUE ecopts;
 };
 
+#ifndef HAVE_RB_IO_T
 /** Ruby's IO, metadata and buffers. */
-typedef struct rb_io {
-
+struct rb_io {
     /** The IO's Ruby level counterpart. */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     VALUE self;
 
     /** stdio ptr for read/write, if available. */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     FILE *stdio_file;
 
     /** file descriptor. */
+    RBIMPL_ATTR_DEPRECATED(("rb_io_descriptor"))
     int fd;
 
     /** mode flags: FMODE_XXXs */
+    RBIMPL_ATTR_DEPRECATED(("rb_io_mode"))
     int mode;
 
     /** child's pid (for pipes) */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     rb_pid_t pid;
 
     /** number of lines read */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     int lineno;
 
     /** pathname for file */
+    RBIMPL_ATTR_DEPRECATED(("rb_io_path"))
     VALUE pathv;
 
     /** finalize proc */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     void (*finalize)(struct rb_io*,int);
 
     /** Write buffer. */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     rb_io_buffer_t wbuf;
 
     /**
      * (Byte)  read   buffer.   Note  also   that  there  is  a   field  called
      * ::rb_io_t::cbuf, which also concerns read IO.
      */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     rb_io_buffer_t rbuf;
 
     /**
@@ -178,20 +188,25 @@ typedef struct rb_io {
      *
      * @see rb_io_set_write_io()
      */
+    RBIMPL_ATTR_DEPRECATED(("rb_io_get_write_io"))
     VALUE tied_io_for_writing;
 
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     struct rb_io_encoding encs; /**< Decomposed encoding flags. */
 
     /** Encoding converter used when reading from this IO. */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     rb_econv_t *readconv;
 
     /**
      * rb_io_ungetc()  destination.   This  buffer   is  read  before  checking
      * ::rb_io_t::rbuf
      */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     rb_io_buffer_t cbuf;
 
     /** Encoding converter used when writing to this IO. */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     rb_econv_t *writeconv;
 
     /**
@@ -200,21 +215,25 @@ typedef struct rb_io {
      * conversion from encoding  X to encoding Y does not  exist, Ruby finds an
      * encoding Z that bridges the two, so that X to Z to Y conversion happens.
      */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     VALUE writeconv_asciicompat;
 
     /** Whether ::rb_io_t::writeconv is already set up. */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     int writeconv_initialized;
 
     /**
      * Value   of    ::rb_io_t::rb_io_enc_t::ecflags   stored    right   before
      * initialising ::rb_io_t::writeconv.
      */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     int writeconv_pre_ecflags;
 
     /**
      * Value of ::rb_io_t::rb_io_enc_t::ecopts stored right before initialising
      * ::rb_io_t::writeconv.
      */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     VALUE writeconv_pre_ecopts;
 
     /**
@@ -224,27 +243,23 @@ typedef struct rb_io {
      *
      * This of course doesn't help inter-process IO interleaves, though.
      */
+    RBIMPL_ATTR_DEPRECATED(("with no replacement"))
     VALUE write_lock;
 
     /**
      * The timeout associated with this IO when performing blocking operations.
      */
+    RBIMPL_ATTR_DEPRECATED(("rb_io_timeout/rb_io_set_timeout"))
     VALUE timeout;
-} rb_io_t;
+};
+#endif
+
+typedef struct rb_io rb_io_t;
 
 /** @alias{rb_io_enc_t} */
 typedef struct rb_io_encoding rb_io_enc_t;
 
 /**
- * @private
- *
- * @deprecated  This macro once was a thing in the old days, but makes no sense
- *              any  longer today.   Exists  here  for backwards  compatibility
- *              only.  You can safely forget about it.
- */
-#define HAVE_RB_IO_T 1
-
-/**
  * @name Possible flags for ::rb_io_t::mode
  *
  * @{
diff --git a/internal/io.h b/internal/io.h
index b5f15499d7..3b2495a0d2 100644
--- a/internal/io.h
+++ b/internal/io.h
@@ -9,8 +9,107 @@
  * @brief      Internal header for IO.
  */
 #include "ruby/ruby.h"          /* for VALUE */
+
+#define HAVE_RB_IO_T
+struct rb_io;
+
 #include "ruby/io.h"            /* for rb_io_t */
 
+/** Ruby's IO, metadata and buffers. */
+typedef struct rb_io {
+
+    /** The IO's Ruby level counterpart. */
+    VALUE self;
+
+    /** stdio ptr for read/write, if available. */
+    FILE *stdio_file;
+
+    /** file descriptor. */
+    int fd;
+
+    /** mode flags: FMODE_XXXs */
+    int mode;
+
+    /** child's pid (for pipes) */
+    rb_pid_t pid;
+
+    /** number of lines read */
+    int lineno;
+
+    /** pathname for file */
+    VALUE pathv;
+
+    /** finalize proc */
+    void (*finalize)(struct rb_io*,int);
+
+    /** Write buffer. */
+    rb_io_buffer_t wbuf;
+
+    /**
+     * (Byte)  read   buffer.   Note  also   that  there  is  a   field  called
+     * ::rb_io_t::cbuf, which also concerns read IO.
+     */
+    rb_io_buffer_t rbuf;
+
+    /**
+     * Duplex IO object, if set.
+     *
+     * @see rb_io_set_write_io()
+     */
+    VALUE tied_io_for_writing;
+
+    struct rb_io_encoding encs; /**< Decomposed encoding flags. */
+
+    /** Encoding converter used when reading from this IO. */
+    rb_econv_t *readconv;
+
+    /**
+     * rb_io_ungetc()  destination.   This  buffer   is  read  before  checking
+     * ::rb_io_t::rbuf
+     */
+    rb_io_buffer_t cbuf;
+
+    /** Encoding converter used when writing to this IO. */
+    rb_econv_t *writeconv;
+
+    /**
+     * This is, when set, an instance  of ::rb_cString which holds the "common"
+     * encoding.   Write  conversion  can  convert strings  twice...   In  case
+     * conversion from encoding  X to encoding Y does not  exist, Ruby finds an
+     * encoding Z that bridges the two, so that X to Z to Y conversion happens.
+     */
+    VALUE writeconv_asciicompat;
+
+    /** Whether ::rb_io_t::writeconv is already set up. */
+    int writeconv_initialized;
+
+    /**
+     * Value   of    ::rb_io_t::rb_io_enc_t::ecflags   stored    right   before
+     * initialising ::rb_io_t::writeconv.
+     */
+    int writeconv_pre_ecflags;
+
+    /**
+     * Value of ::rb_io_t::rb_io_enc_t::ecopts stored right before initialising
+     * ::rb_io_t::writeconv.
+     */
+    VALUE writeconv_pre_ecopts;
+
+    /**
+     * This is a Ruby  level mutex.  It avoids multiple threads  to write to an
+     * IO at  once; helps  for instance rb_io_puts()  to ensure  newlines right
+     * next to its arguments.
+     *
+     * This of course doesn't help inter-process IO interleaves, though.
+     */
+    VALUE write_lock;
+
+    /**
+     * The timeout associated with this IO when performing blocking operations.
+     */
+    VALUE timeout;
+} rb_io_t;
+
 /* io.c */
 void ruby_set_inplace_mode(const char *);
 void rb_stdio_set_default_encoding(void);