Merge pull request #325 from Shopify/pool-raw-packer

Implement Factory::Pool #packer and #unpacker methods

Author: byroot

ChangeLog

@@ -1,3 +1,4 @@
+* Implement `Factory::Pool#unpacker` and `Factory::Pool#packer` to allow for more precise serialization.
 * Require Ruby 2.5+.
 
 2023-03-03 1.6.1:

README.md

@@ -211,6 +211,33 @@ factory.register_type(
 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.

doclib/msgpack/factory.rb

@@ -124,8 +124,6 @@ class Pool
       # @param data [String]
       # @return [Object] deserialized object
       #
-      # See Unpacker#initialize for supported options.
-      #
       def load(data)
       end
 
@@ -140,6 +138,28 @@ def load(data)
       #
       def dump(object)
       end
+
+      #
+      # Yields an Unpacker from the pool, and check it back in.
+      #
+      # The unpacker should no longer be held after the block has returned.
+      #
+      # @yieldparam unpacker [MessagePack::Unpacker]
+      # @returns [Object] the block return value
+      #
+      def unpacker(&block)
+      end
+
+      #
+      # Yields a Packer from the pool, and check it back in.
+      #
+      # The packer should no longer be held after the block has returned.
+      #
+      # @yieldparam packer [MessagePack::Packer]
+      # @returns [Object] the block return value
+      #
+      def packer(&block)
+      end
     end
   end
 end

doclib/msgpack/packer.rb

@@ -176,9 +176,19 @@ def size
     def empty?
     end
 
+    #
+    # Returns all data in the buffer as a string, and reset the buffer.
+    #
+    # @return [String]
+    #
+    def full_pack
+    end
+
     #
     # Returns all data in the buffer as a string. Same as buffer.to_str.
     #
+    # Does not empty the buffer, in most case _full_pack_ is prefered.
+    #
     # @return [String]
     #
     def to_str

ext/java/org/msgpack/jruby/Factory.java

@@ -92,7 +92,7 @@ public IRubyObject registerType(ThreadContext ctx, IRubyObject[] args) {
     RubyHash options = null;
 
     if (isFrozen()) {
-        throw runtime.newRuntimeError("can't modify frozen Factory");
+        throw runtime.newFrozenError("MessagePack::Factory");
     }
 
     if (args.length == 2) {

ext/java/org/msgpack/jruby/Packer.java

@@ -96,6 +96,9 @@ public IRubyObject registeredTypesInternal(ThreadContext ctx) {
   @JRubyMethod(name = "register_type", required = 2, optional = 1)
   public IRubyObject registerType(ThreadContext ctx, IRubyObject[] args, final Block block) {
     Ruby runtime = ctx.runtime;
+    if (isFrozen()) {
+        throw runtime.newFrozenError("MessagePack::Packer");
+    }
     IRubyObject type = args[0];
     IRubyObject mod = args[1];
 

ext/java/org/msgpack/jruby/Unpacker.java

@@ -130,6 +130,9 @@ public IRubyObject registeredTypesInternal(ThreadContext ctx) {
   @JRubyMethod(name = "register_type", required = 1, optional = 2)
   public IRubyObject registerType(ThreadContext ctx, IRubyObject[] args, final Block block) {
     Ruby runtime = ctx.runtime;
+    if (isFrozen()) {
+        throw runtime.newFrozenError("MessagePack::Unpacker");
+    }
     IRubyObject type = args[0];
 
     RubyModule extModule;

ext/msgpack/factory_class.c

@@ -212,7 +212,7 @@ static VALUE Factory_register_type(int argc, VALUE* argv, VALUE self)
     VALUE packer_proc, unpacker_proc;
 
     if (OBJ_FROZEN(self)) {
-        rb_raise(rb_eRuntimeError, "can't modify frozen Factory");
+        rb_raise(rb_eFrozenError, "can't modify frozen MessagePack::Factory");
     }
 
     switch (argc) {

ext/msgpack/packer_class.c

@@ -349,6 +349,10 @@ static VALUE Packer_registered_types_internal(VALUE self)
 
 static VALUE Packer_register_type(int argc, VALUE* argv, VALUE self)
 {
+    if (OBJ_FROZEN(self)) {
+        rb_raise(rb_eFrozenError, "can't modify frozen MessagePack::Packer");
+    }
+
     msgpack_packer_t *pk = MessagePack_Packer_get(self);
 
     int ext_type;

ext/msgpack/unpacker_class.c

@@ -348,6 +348,10 @@ static VALUE Unpacker_registered_types_internal(VALUE self)
 
 static VALUE Unpacker_register_type(int argc, VALUE* argv, VALUE self)
 {
+    if (OBJ_FROZEN(self)) {
+        rb_raise(rb_eFrozenError, "can't modify frozen MessagePack::Unpacker");
+    }
+
     msgpack_unpacker_t *uk = MessagePack_Unpacker_get(self);
 
     int ext_type;
@@ -446,7 +450,7 @@ void MessagePack_Unpacker_module_init(VALUE mMessagePack)
     rb_define_method(cMessagePack_Unpacker, "read_array_header", Unpacker_read_array_header, 0);
     rb_define_method(cMessagePack_Unpacker, "read_map_header", Unpacker_read_map_header, 0);
     rb_define_method(cMessagePack_Unpacker, "feed", Unpacker_feed_reference, 1);
-    rb_define_method(cMessagePack_Unpacker, "feed_reference", Unpacker_feed_reference, 1);
+    rb_define_alias(cMessagePack_Unpacker, "feed_reference", "feed");
     rb_define_method(cMessagePack_Unpacker, "each", Unpacker_each, 0);
     rb_define_method(cMessagePack_Unpacker, "feed_each", Unpacker_feed_each, 1);
     rb_define_method(cMessagePack_Unpacker, "reset", Unpacker_reset, 0);