Formal specification of field types for abstract IO types

Most concrete IO types declare that a subset of their fields
are other abstract IO types. As a result, if `obj1::IO`, and
`obj2 = obj1.fieldwithabstracttype`, then inference has no way of
knowing what type `obj2.status` returns. When `obj2.status` is used as
an argument for `Base.somefunction`, this leaves such code vulnerable
to invalidation via package specializations of `Base.somefunction`
even when in practice there is no risk that any IO code will call
the new package-supplied method.

This provides a more formal interface for three non-exported
abstract types: `LibuvStream`, `LibuvServer`, and `AbstractPipe`.

Author: timholy

base/io.jl

@@ -333,8 +333,27 @@ function open(f::Function, args...; kwargs...)
     end
 end
 
-# Generic wrappers around other IO objects
+"""
+    AbstractPipe
+
+`AbstractPipe` is the abstract supertype for IO pipes that provide for communication between processes.
+
+If `pipe isa AbstractPipe`, it must obey the following interface:
+
+- `pipe.in` or `pipe.in_stream`, if present, must be of type `IO` and be used to provide input to the pipe
+- `pipe.out` or `pipe.out_stream`, if present, must be of type `IO` and be used for output from the pipe
+- `pipe.err` or `pipe.err_stream`, if present, must be of type `IO` and be used for writing errors from the pipe
+"""
 abstract type AbstractPipe <: IO end
+
+function getproperty(pipe::AbstractPipe, name::Symbol)
+    if name === :in || name === :in_stream || name === :out || name === :out_stream ||
+       name === :err || name === :err_stream
+        return getfield(pipe, name)::IO
+    end
+    return getfield(pipe, name)
+end
+
 function pipe_reader end
 function pipe_writer end
 

base/stream.jl

@@ -13,9 +13,67 @@ end
 
 ## types ##
 abstract type IOServer end
+"""
+    LibuvServer
+
+An abstract type for IOServers handled by libuv.
+
+If `server isa LibuvServer`, it must obey the following interface:
+
+- `server.handle` must be a `Ptr{Cvoid}`
+- `server.status` must be an `Int`
+- `server.cond` must be a `GenericCondition`
+"""
 abstract type LibuvServer <: IOServer end
+
+function getproperty(server::LibuvServer, name::Symbol)
+    if name === :handle
+        return getfield(server, :handle)::Ptr{Cvoid}
+    elseif name === :status
+        return getfield(server, :status)::Int
+    elseif name === :cond
+        return getfield(server, :cond)::GenericCondition
+    else
+        return getfield(server, name)
+    end
+end
+
+"""
+    LibuvStream
+
+An abstract type for IO streams handled by libuv.
+
+If`stream isa LibuvStream`, it must obey the following interface:
+
+- `stream.handle`, if present, must be a `Ptr{Cvoid}`
+- `stream.status`, if present, must be an `Int`
+- `stream.buffer`, if present, must be an `IOBuffer`
+- `stream.sendbuf`, if present, must be a `Union{Nothing,IOBuffer}`
+- `stream.cond`, if present, must be a `GenericCondition`
+- `stream.lock`, if present, must be an `AbstractLock`
+- `stream.throttle`, if present, must be an `Int`
+"""
 abstract type LibuvStream <: IO end
 
+function getproperty(stream::LibuvStream, name::Symbol)
+    if name === :handle
+        return getfield(stream, :handle)::Ptr{Cvoid}
+    elseif name === :status
+        return getfield(stream, :status)::Int
+    elseif name === :buffer
+        return getfield(stream, :buffer)::IOBuffer
+    elseif name === :sendbuf
+        return getfield(stream, :sendbuf)::Union{Nothing,IOBuffer}
+    elseif name === :cond
+        return getfield(stream, :cond)::GenericCondition
+    elseif name === :lock
+        return getfield(stream, :lock)::AbstractLock
+    elseif name === :throttle
+        return getfield(stream, :throttle)::Int
+    else
+        return getfield(stream, name)
+    end
+end
 
 # IO
 # +- GenericIOBuffer{T<:AbstractArray{UInt8,1}} (not exported)