ed-precompiled_msgpack 1.8.0

data/README.md

@@ -0,0 +1,302 @@
+# MessagePack
+
+[MessagePack](http://msgpack.org) is an efficient binary serialization format.
+It lets you exchange data among multiple languages like JSON but it's faster and smaller.
+For example, small integers (like flags or error code) are encoded into a single byte,
+and typical short strings only require an extra byte in addition to the strings themselves.
+
+If you ever wished to use JSON for convenience (storing an image with metadata) but could
+not for technical reasons (binary data, size, speed...), MessagePack is a perfect replacement.
+
+```ruby
+require 'msgpack'
+msg = [1,2,3].to_msgpack  #=> "\x93\x01\x02\x03"
+MessagePack.unpack(msg)   #=> [1,2,3]
+```
+
+Add msgpack to your Gemfile to install with Bundler:
+
+```ruby
+# Gemfile
+gem 'msgpack'
+```
+
+Or, use RubyGems to install:
+
+    gem install msgpack
+
+Or, build msgpack-ruby and install from a checked-out msgpack-ruby repository:
+
+    bundle
+    rake
+    gem install --local pkg/msgpack
+
+
+## Use cases
+
+* Create REST API returing MessagePack using Rails + [RABL](https://github.com/nesquena/rabl)
+* Store objects efficiently serialized by msgpack on memcached or Redis
+  * In fact Redis supports msgpack in [EVAL-scripts](https://redis.io/docs/latest/commands/eval/)
+* Upload data in efficient format from mobile devices such as smartphones
+  * MessagePack works on iPhone/iPad and Android. See also [Objective-C](https://github.com/msgpack/msgpack-objectivec) and [Java](https://github.com/msgpack/msgpack-java) implementations
+* Design a portable protocol to communicate with embedded devices
+  * Check also [Fluentd](https://www.fluentd.org) which is a log collector which uses msgpack for the log format (they say it uses JSON but actually it's msgpack, which is compatible with JSON)
+* Exchange objects between software components written in different languages
+  * You'll need a flexible but efficient format so that components exchange objects while keeping compatibility
+
+## Portability
+
+MessagePack for Ruby should run on x86, ARM, PowerPC, SPARC and other CPU architectures.
+
+And it works with MRI (CRuby) and Rubinius.
+Patches to improve portability are highly welcomed.
+
+
+## Serializing objects
+
+Use `MessagePack.pack` or `to_msgpack`:
+
+```ruby
+require 'msgpack'
+msg = MessagePack.pack(obj)  # or
+msg = obj.to_msgpack
+File.binwrite('mydata.msgpack', msg)
+```
+
+### Streaming serialization
+
+Packer provides advanced API to serialize objects in streaming style:
+
+```ruby
+# serialize a 2-element array [e1, e2]
+pk = MessagePack::Packer.new(io)
+pk.write_array_header(2).write(e1).write(e2).flush
+```
+
+See [API reference](http://ruby.msgpack.org/MessagePack/Packer.html) for details.
+
+## Deserializing objects
+
+Use `MessagePack.unpack`:
+
+```ruby
+require 'msgpack'
+msg = File.binread('mydata.msgpack')
+obj = MessagePack.unpack(msg)
+```
+
+### Streaming deserialization
+
+Unpacker provides advanced API to deserialize objects in streaming style:
+
+```ruby
+# deserialize objects from an IO
+u = MessagePack::Unpacker.new(io)
+u.each do |obj|
+  # ...
+end
+```
+
+or event-driven style which works well with EventMachine:
+
+```ruby
+# event-driven deserialization
+def on_read(data)
+  @u ||= MessagePack::Unpacker.new
+  @u.feed_each(data) {|obj|
+     # ...
+  }
+end
+```
+
+See [API reference](http://ruby.msgpack.org/MessagePack/Unpacker.html) for details.
+
+## Serializing and deserializing symbols
+
+By default, symbols are serialized as strings:
+
+```ruby
+packed = :symbol.to_msgpack     # => "\xA6symbol"
+MessagePack.unpack(packed)      # => "symbol"
+```
+
+This can be customized by registering an extension type for them:
+
+```ruby
+MessagePack::DefaultFactory.register_type(0x00, Symbol)
+
+# symbols now survive round trips
+packed = :symbol.to_msgpack     # => "\xc7\x06\x00symbol"
+MessagePack.unpack(packed)      # => :symbol
+```
+
+The extension type for symbols is configurable like any other extension type.
+For example, to customize how symbols are packed you can just redefine
+Symbol#to_msgpack_ext. Doing this gives you an option to prevent symbols from
+being serialized altogether by throwing an exception:
+
+```ruby
+class Symbol
+  def to_msgpack_ext
+    raise "Serialization of symbols prohibited"
+  end
+end
+
+MessagePack::DefaultFactory.register_type(0x00, Symbol)
+
+[1, :symbol, 'string'].to_msgpack  # => RuntimeError: Serialization of symbols prohibited
+```
+
+## Serializing and deserializing Time instances
+
+There are the timestamp extension type in MessagePack,
+but it is not registered by default.
+
+To map Ruby's Time to MessagePack's timestamp for the default factory:
+
+```ruby
+MessagePack::DefaultFactory.register_type(
+  MessagePack::Timestamp::TYPE, # or just -1
+  Time,
+  packer: MessagePack::Time::Packer,
+  unpacker: MessagePack::Time::Unpacker
+)
+```
+
+See [API reference](http://ruby.msgpack.org/) for details.
+
+## Extension Types
+
+Packer and Unpacker support [Extension types of MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md#types-extension-type).
+
+```ruby
+# register how to serialize custom class at first
+pk = MessagePack::Packer.new(io)
+pk.register_type(0x01, MyClass1, :to_msgpack_ext) # equal to pk.register_type(0x01, MyClass)
+pk.register_type(0x02, MyClass2){|obj| obj.how_to_serialize() } # blocks also available
+
+# almost same API for unpacker
+uk = MessagePack::Unpacker.new()
+uk.register_type(0x01, MyClass1, :from_msgpack_ext)
+uk.register_type(0x02){|data| MyClass2.create_from_serialized_data(data) }
+```
+
+`MessagePack::Factory` is to create packer and unpacker which have same extension types.
+
+```ruby
+factory = MessagePack::Factory.new
+factory.register_type(0x01, MyClass1) # same with next line
+factory.register_type(0x01, MyClass1, packer: :to_msgpack_ext, unpacker: :from_msgpack_ext)
+pk = factory.packer(options_for_packer)
+uk = factory.unpacker(options_for_unpacker)
+```
+
+For `MessagePack.pack` and `MessagePack.unpack`, default packer/unpacker refer `MessagePack::DefaultFactory`. Call `MessagePack::DefaultFactory.register_type` to enable types process globally.
+
+```ruby
+MessagePack::DefaultFactory.register_type(0x03, MyClass3)
+MessagePack.unpack(data_with_ext_typeid_03) #=> MyClass3 instance
+```
+
+Alternatively, extension types can call the packer or unpacker recursively to generate the extension data:
+
+```ruby
+Point = Struct.new(:x, :y)
+factory = MessagePack::Factory.new
+factory.register_type(
+  0x01,
+  Point,
+  packer: ->(point, packer) {
+    packer.write(point.x)
+    packer.write(point.y)
+  },
+  unpacker: ->(unpacker) {
+    x = unpacker.read
+    y = unpacker.read
+    Point.new(x, y)
+  },
+  recursive: true,
+)
+factory.load(factory.dump(Point.new(12, 34))) # => #<struct Point x=12, y=34>
+```
+
+## Pooling
+
+Creating `Packer` and `Unpacker` objects is expensive. For best performance it is preferable to re-use these objects.
+
+`MessagePack::Factory#pool` makes that easier:
+
+```ruby
+factory = MessagePack::Factory.new
+factory.register_type(
+  0x01,
+  Point,
+  packer: ->(point, packer) {
+    packer.write(point.x)
+    packer.write(point.y)
+  },
+  unpacker: ->(unpacker) {
+    x = unpacker.read
+    y = unpacker.read
+    Point.new(x, y)
+  },
+  recursive: true,
+)
+pool = factory.pool(5) # The pool size should match the number of threads expected to use the factory concurrently.
+
+pool.load(pool.dump(Point.new(12, 34))) # => #<struct Point x=12, y=34>
+```
+
+## Buffer API
+
+MessagePack for Ruby provides a buffer API so that you can read or write data by hand, not via Packer or Unpacker API.
+
+This [MessagePack::Buffer](http://ruby.msgpack.org/MessagePack/Buffer.html) is backed with a fixed-length shared memory pool which is very fast for small data (<= 4KB),
+and has zero-copy capability which significantly affects performance to handle large binary data.
+
+## How to build and run tests
+
+Before building msgpack, you need to install bundler and dependencies.
+
+    gem install bundler
+    bundle install
+
+Then, you can run the tasks as follows:
+
+### Build
+
+    bundle exec rake build
+
+### Run tests
+
+    bundle exec rake spec
+
+### Generating docs
+
+    bundle exec rake doc
+
+## How to build -java rubygems
+
+To build -java gems for JRuby, run:
+
+    rake build:java
+
+If this directory has Gemfile.lock (generated with MRI), remove it beforehand.
+
+## Updating documents
+
+Online documentation (https://ruby.msgpack.org) is generated from the gh-pages branch.
+To update documents in gh-pages branch:
+
+    bundle exec rake doc
+    git checkout gh-pages
+    cp -a doc/* ./
+
+## Copyright
+
+* Author
+  * Sadayuki Furuhashi <frsyuki@gmail.com>
+* Copyright
+  * Copyright (c) 2008-2015 Sadayuki Furuhashi
+* License
+  * Apache License, Version 2.0

data/ext/java/org/msgpack/jruby/Buffer.java

@@ -0,0 +1,233 @@
+package org.msgpack.jruby;
+
+
+import java.nio.ByteBuffer;
+
+import org.jruby.Ruby;
+import org.jruby.RubyClass;
+import org.jruby.RubyObject;
+import org.jruby.RubyHash;
+import org.jruby.RubyIO;
+import org.jruby.RubyInteger;
+import org.jruby.runtime.builtin.IRubyObject;
+import org.jruby.anno.JRubyClass;
+import org.jruby.anno.JRubyMethod;
+import org.jruby.runtime.ThreadContext;
+import org.jruby.runtime.ObjectAllocator;
+import org.jruby.util.ByteList;
+
+import org.jcodings.Encoding;
+
+
+@JRubyClass(name="MessagePack::Buffer")
+public class Buffer extends RubyObject {
+  private static final long serialVersionUID = 8441244627425629412L;
+  private transient IRubyObject io;
+  private transient ByteBuffer buffer;
+  private boolean writeMode;
+  private transient Encoding binaryEncoding;
+
+  private static final int CACHE_LINE_SIZE = 64;
+  private static final int ARRAY_HEADER_SIZE = 24;
+
+  public Buffer(Ruby runtime, RubyClass type) {
+    super(runtime, type);
+  }
+
+  static class BufferAllocator implements ObjectAllocator {
+    public IRubyObject allocate(Ruby runtime, RubyClass type) {
+      return new Buffer(runtime, type);
+    }
+  }
+
+  @JRubyMethod(name = "initialize", optional = 2)
+  public IRubyObject initialize(ThreadContext ctx, IRubyObject[] args) {
+    if (args.length > 0) {
+      IRubyObject io = args[0];
+      if (io.respondsTo("close") && (io.respondsTo("read") || (io.respondsTo("write") && io.respondsTo("flush")))) {
+        this.io = io;
+      }
+    }
+    this.buffer = ByteBuffer.allocate(CACHE_LINE_SIZE - ARRAY_HEADER_SIZE);
+    this.writeMode = true;
+    this.binaryEncoding = ctx.runtime.getEncodingService().getAscii8bitEncoding();
+    return this;
+  }
+
+  private void ensureRemainingCapacity(int c) {
+    if (!writeMode) {
+      buffer.compact();
+      writeMode = true;
+    }
+    if (buffer.remaining() < c) {
+      int newLength = Math.max(buffer.capacity() + (buffer.capacity() >> 1), buffer.capacity() + c);
+      newLength += CACHE_LINE_SIZE - ((ARRAY_HEADER_SIZE + newLength) % CACHE_LINE_SIZE);
+      buffer = ByteBuffer.allocate(newLength).put(buffer.array(), 0, buffer.position());
+    }
+  }
+
+  private void ensureReadMode() {
+    if (writeMode) {
+      buffer.flip();
+      writeMode = false;
+    }
+  }
+
+  private int rawSize() {
+    if (writeMode) {
+      return buffer.position();
+    } else {
+      return buffer.limit() - buffer.position();
+    }
+  }
+
+  @JRubyMethod(name = "clear")
+  public IRubyObject clear(ThreadContext ctx) {
+    if (!writeMode) {
+      buffer.compact();
+      writeMode = true;
+    }
+    buffer.clear();
+    return ctx.runtime.getNil();
+  }
+
+  @JRubyMethod(name = "size")
+  public IRubyObject size(ThreadContext ctx) {
+    return ctx.runtime.newFixnum(rawSize());
+  }
+
+  @JRubyMethod(name = "empty?")
+  public IRubyObject isEmpty(ThreadContext ctx) {
+    return rawSize() == 0 ? ctx.runtime.getTrue() : ctx.runtime.getFalse();
+  }
+
+  private IRubyObject bufferWrite(ThreadContext ctx, IRubyObject str) {
+    ByteList bytes = str.asString().getByteList();
+    int length = bytes.length();
+    ensureRemainingCapacity(length);
+    buffer.put(bytes.unsafeBytes(), bytes.begin(), length);
+    return ctx.runtime.newFixnum(length);
+
+  }
+
+  @JRubyMethod(name = "write", alias = {"<<"})
+  public IRubyObject write(ThreadContext ctx, IRubyObject str) {
+    if (io == null) {
+      return bufferWrite(ctx, str);
+    } else {
+      return io.callMethod(ctx, "write", str);
+    }
+  }
+
+  private void feed(ThreadContext ctx) {
+    if (io != null) {
+      bufferWrite(ctx, io.callMethod(ctx, "read"));
+    }
+  }
+
+  private IRubyObject readCommon(ThreadContext ctx, IRubyObject[] args, boolean raiseOnUnderflow) {
+    feed(ctx);
+    int length = rawSize();
+    if (args != null && args.length == 1) {
+      length = (int) args[0].convertToInteger().getLongValue();
+    }
+    if (raiseOnUnderflow && rawSize() < length) {
+      throw ctx.runtime.newEOFError();
+    }
+    int readLength = Math.min(length, rawSize());
+    if (readLength == 0 && length > 0) {
+      return ctx.runtime.getNil();
+    } else if (readLength == 0) {
+      return ctx.runtime.newString();
+    } else {
+      ensureReadMode();
+      byte[] bytes = new byte[readLength];
+      buffer.get(bytes);
+      ByteList byteList = new ByteList(bytes, binaryEncoding);
+      return ctx.runtime.newString(byteList);
+    }
+  }
+
+  @JRubyMethod(name = "read", optional = 1)
+  public IRubyObject read(ThreadContext ctx, IRubyObject[] args) {
+    return readCommon(ctx, args, false);
+  }
+
+  @JRubyMethod(name = "read_all", optional = 1)
+  public IRubyObject readAll(ThreadContext ctx, IRubyObject[] args) {
+    return readCommon(ctx, args, true);
+  }
+
+  private IRubyObject skipCommon(ThreadContext ctx, IRubyObject _length, boolean raiseOnUnderflow) {
+    feed(ctx);
+    int length = (int) _length.convertToInteger().getLongValue();
+    if (raiseOnUnderflow && rawSize() < length) {
+      throw ctx.runtime.newEOFError();
+    }
+    ensureReadMode();
+    int skipLength = Math.min(length, rawSize());
+    buffer.position(buffer.position() + skipLength);
+    return ctx.runtime.newFixnum(skipLength);
+  }
+
+  @JRubyMethod(name = "skip")
+  public IRubyObject skip(ThreadContext ctx, IRubyObject length) {
+    return skipCommon(ctx, length, false);
+  }
+
+  @JRubyMethod(name = "skip_all")
+  public IRubyObject skipAll(ThreadContext ctx, IRubyObject length) {
+    return skipCommon(ctx, length, true);
+  }
+
+  public boolean hasIo() {
+    return io != null;
+  }
+
+  @JRubyMethod(name = "to_s", alias = {"to_str"})
+  public IRubyObject toS(ThreadContext ctx) {
+    ensureReadMode();
+    int length = buffer.limit() - buffer.position();
+    ByteList str = new ByteList(buffer.array(), buffer.position(), length, binaryEncoding, true);
+    return ctx.runtime.newString(str);
+  }
+
+  @JRubyMethod(name = "to_a")
+  public IRubyObject toA(ThreadContext ctx) {
+    return ctx.runtime.newArray(toS(ctx));
+  }
+
+  @JRubyMethod(name = "io")
+  public IRubyObject getIo(ThreadContext ctx) {
+    return io == null ? ctx.runtime.getNil() : io;
+  }
+
+  @JRubyMethod(name = "flush")
+  public IRubyObject flush(ThreadContext ctx) {
+    if (io == null) {
+      return ctx.runtime.getNil();
+    } else {
+      return io.callMethod(ctx, "flush");
+    }
+  }
+
+  @JRubyMethod(name = "close")
+  public IRubyObject close(ThreadContext ctx) {
+    if (io == null) {
+      return ctx.runtime.getNil();
+    } else {
+      return io.callMethod(ctx, "close");
+    }
+  }
+
+  @JRubyMethod(name = "write_to")
+  public IRubyObject writeTo(ThreadContext ctx, IRubyObject io) {
+    return io.callMethod(ctx, "write", readCommon(ctx, null, false));
+  }
+
+  public ByteList getBytes() {
+    byte[] bytes = new byte[rawSize()];
+    buffer.get(bytes);
+    return new ByteList(bytes, binaryEncoding);
+  }
+}