Skip to content

Latest commit

 

History

History
42 lines (35 loc) · 2.61 KB

README.md

File metadata and controls

42 lines (35 loc) · 2.61 KB
Raw

ruby-io

A clean sheet redesign of Ruby's IO class. Includes Blocking and Nonblocking implementations of all major components.

This project exists to try out some ideas. I expect a few blind alleys before I settle on the API that I like and a good implementation to back it.

Goals

  • Be considered as the new core IO classes for Ruby 3.0
  • New API
    • Provide Synchronous IO with a modern API for best single-threaded straight line performance
    • Provide Asynchronous / Nonblocking IO with a modern API for the best multi-threaded performance
    • Make both the blocking & nonblocking APIs consistent/identical. Switching between them shouldn't require any (?) code changes.
  • Implement the State pattern internally to simplify error handling and eliminate a lot of hairy if/then/else logic
  • Utilize keyword arguments everywhere to simplify and clarify method signatures
  • Allow for the new IO classes to live side-by-side with the core IO classes in Ruby (no namespace conflicts)
  • New classes include a sane class inheritance and composition structure
  • Only expose POSIX-compliant functions
    • Syscalls that are platform-specific can be sideloaded via mixins or some other mechanism
  • Allow programmer to choose Error reporting policy; built-in choices to include POSIX-style return codes with errno, and Exceptions. One or the other will be active per IO instance.
  • Allow programmer to choose Multithread reporting policy for when using objects across multiple threads: silent, warn, fatal options
  • Move unicode support to the periphery of the IO classes and only incur unicode overhead when the programmer chooses to use it
  • Pure Ruby implementation; other runtimes could potentially load native code (C for MRI, Java for JRuby) if performance dictates.

Runtime Support

Tested and works on:

  • MRI 2.4.0, 2.5.0, 2.6.0dev
  • Rubinius 3.87 (minimum required version)
  • TruffleRuby (master as of 20171230)
  • JRuby (master as of 20180102)
    • The default Multithread policy warns about accessing IO methods from multiple threads. There is an open issue (find number) regarding a bug where Thread.current is incorrectly reported for thread-backed Fibers. While it tracks the proper parent thread internally, it reports the actual pool thread backing the running Fiber.
    • This problem is tracked in Issues 1717 and 1806 in JRuby.

Platform Support

Tested and working on:

  • OSX 10.12.6 and 10.13.2 (native kqueue support)
  • Linux kernel 4.13 (native epoll support)

Philosophy

Please refer to the FAQ for this topic.

Examples

(c) Chuck Remes 2018