Merge pull request #247 from JuliaInterop/iostream

Deprecate `Base.convert(IOStream, ::Message)`

Author: JamesWrigley

docs/src/_changelog.md

@@ -14,6 +14,10 @@ Changelog](https://keepachangelog.com).
   1.11 ([#244]).
 - Full [Bindings](@ref) to libzmq ([#232]).
 
+### Deprecated
+- The `Base.convert(IOStream, ::Message)` method has been deprecated due to
+  buggy behaviour, use `IOBuffer(msg)` instead ([#247]).
+
 ### Fixed
 - Fixed [`isfreed()`](@ref), which would previously return the wrong values
   ([#245]).

src/message.jl

@@ -23,9 +23,31 @@ function gc_free_fn(data::Ptr{Cvoid}, hint::Ptr{Cvoid})
 end
 
 """
-High-level Message object for sending/receiving ZMQ messages in shared buffers.
+    mutable struct Message <: AbstractArray{UInt8, 1}
+
+High-level `Message` object for sending/receiving ZMQ messages in shared
+buffers. As an `AbstractArray`, it supports common (non-resizeable) array
+behaviour.
+
+# Examples
+```jldoctest
+julia> using ZMQ
+
+julia> m = Message("foo");
+
+julia> Char(m[1])            # Array indexing
+'f': ASCII/Unicode U+0066 (category Ll: Letter, lowercase)
+
+julia> m[end] = Int('g');    # Array assignment
+
+julia> unsafe_string(m)      # Conversion to string (only do this if you know the message is a string)
+"fog"
+
+julia> IOBuffer(m)           # Create a zero-copy IOBuffer
+IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=3, maxsize=Inf, ptr=1, mark=-1)
+```
 """
-mutable struct Message <: AbstractArray{UInt8,1}
+mutable struct Message <: AbstractArray{UInt8, 1}
     # Matching the declaration in the header: char _[64];
     w_padding::_Message
     handle::Ptr{Cvoid} # index into gc_protect, if any
@@ -164,6 +186,7 @@ Base.strides(::Message) = (1,)
 # Build an IOStream from a message
 # Copies the data
 function Base.convert(::Type{IOStream}, zmsg::Message)
+    Base.depwarn("convert(IOStream, ::Message) is deprecated, use `IOBuffer(zmsg)` instead to make a zero-copy IOBuffer from a Message.", :convert)
     s = IOBuffer()
     write(s, zmsg)
     return s

test/runtests.jl

@@ -121,8 +121,7 @@ end
 
     ZMQ.send(s2, Message("another test request"))
     msg = ZMQ.recv(s1)
-    o=convert(IOStream, msg)
-    seek(o, 0)
+    o = IOBuffer(msg)
     @test String(take!(o)) == "another test request"
     ZMQ.send(s1) do io
         print(io, "buffer ")
@@ -218,6 +217,7 @@ end
     @test !Bool(m.more)
     @test_throws ErrorException m.more = true
     @test ZMQ.isfreed(m)
+    @test_logs (:warn, r"convert(.+) is deprecated") convert(IOStream, m)
 end
 
 @testset "ZMQ resource management" begin