Cleanup buffer

jls/lang/Buffer-buffer.lua

@@ -1,20 +1,11 @@
 local class = require('jls.lang.class')
 
 local bufferLib = require('buffer')
-assert(bufferLib._VERSION >= '0.3', 'bad buffer lib version '..tostring(bufferLib._VERSION))
+assert(type(bufferLib.toreference) == 'function', 'bad buffer lib version '..tostring(bufferLib._VERSION))
 
-return class.create(function(buffer)
+return class.create('jls.lang.Buffer', function(buffer)
 
   function buffer:initialize(value, size)
-    if type(value) ~= 'userdata' then
-      error('invalid buffer type '..type(value))
-    end
-    if size == nil then
-      size = bufferLib.len(value)
-    end
-    if math.type(size) ~= 'integer' or size <= 0 then
-      error('invalid size '..tostring(size))
-    end
     self.buffer = value
     self.size = size
   end
@@ -51,18 +42,15 @@ return class.create(function(buffer)
     return bufferLib.toreference(self.buffer, nil, 'jls.lang.Buffer')
   end
 
-  function buffer:toString()
-    return bufferLib.sub(self.buffer, 1, self.size)
-  end
-
 end, function(Buffer)
 
-  function Buffer.allocate(sizeOrData)
-    return Buffer:new(bufferLib.new(sizeOrData))
+  function Buffer.allocate(size)
+    return Buffer:new(bufferLib.new(size), size)
   end
 
   function Buffer.fromReference(reference)
-    return Buffer:new(bufferLib.fromreference(reference, nil, 'jls.lang.Buffer'))
+    local buffer, size = bufferLib.fromreference(reference, nil, 'jls.lang.Buffer')
+    return Buffer:new(buffer, size)
   end
 
 end)

jls/lang/Buffer.lua

@@ -1 +1,101 @@
-return require('jls.lang.loader').requireOne('jls.lang.Buffer-buffer', 'jls.lang.Buffer-')
+--- Represents a byte array to store temporary data.
+-- @module jls.lang.Buffer
+-- @pragma nostrip
+
+local class = require('jls.lang.class')
+
+--- The Buffer class.
+-- @type Buffer
+return class.create(function(buffer)
+
+  --- Returns the size of the buffer.
+  -- @return The size of the buffer
+  -- @function buffer:length
+  buffer.length = class.notImplementedFunction
+
+  --- Returns the string at the specified position.
+  -- @tparam[opt] number from The start position, default to 1
+  -- @tparam[opt] number to The end position included, default to this buffer size
+  -- @return The string at the specified position
+  -- @function buffer:get
+  buffer.get = class.notImplementedFunction
+
+  --- Sets the string at the specified position.
+  -- @param value The value to set in this buffer, could be a buffer or a string
+  -- @tparam[opt] number offset The position in this buffer to set, default to 1
+  -- @tparam[opt] number from The start position in the value, default to 1
+  -- @tparam[opt] number to The end position in the value included, default to this buffer size
+  -- @function buffer:set
+  buffer.set = class.notImplementedFunction
+
+  --- Returns the bytes at the specified position.
+  -- @tparam[opt] number from The start position, default to 1
+  -- @tparam[opt] number to The end position included, default to from
+  -- @return The bytes at the specified position
+  -- @function buffer:getBytes
+  buffer.getBytes = class.notImplementedFunction
+
+  --- Sets the bytes at the specified position.
+  -- @tparam number at The position in this buffer to set, default to 1
+  -- @param ... The bytes
+  -- @function buffer:setBytes
+  buffer.setBytes = class.notImplementedFunction
+
+  --- Returns a reference for this buffer.
+  -- @treturn string a reference for this buffer
+  -- @function buffer:toReference
+  buffer.toReference = class.notImplementedFunction
+
+end, function(Buffer)
+
+  local function getClassName(mode)
+    if mode == 'local' then
+      return require('jls.lang.BufferLocal')
+    elseif mode == 'global' then
+      return require('jls.lang.BufferGlobal')
+    elseif mode == 'shared' then
+      return require('jls.lang.BufferShared')
+    end
+    error('invalid buffer mode '..tostring(mode))
+  end
+
+  --- Returns a new buffer for the specified mode.  
+  -- A local buffer resides in the Lua state.
+  -- A global buffer resides out of the Lua state but in the Lua process.
+  -- A shared buffer resides out of the Lua process but in the host.
+  -- @tparam number size the size to allocate, could be a non empty string
+  -- @tparam[opt] string mode the mode of buffer, defaults to local
+  -- @return The new allocated buffer
+  function Buffer.allocate(size, mode)
+    if type(size) == 'string' then
+      local b = Buffer.allocate(#size, mode)
+      b:set(size)
+      return b
+    end
+    if math.type(size) ~= 'integer' or size <= 0 then
+      error('invalid size '..tostring(size))
+    end
+    if mode == nil then
+      mode = 'local'
+    end
+    return getClassName(mode).allocate(size, mode)
+  end
+
+  --- Returns the buffer represented by the specified reference.
+  -- @tparam string reference the reference
+  -- @tparam[opt] string mode the mode of buffer
+  -- @return The referenced buffer
+  function Buffer.fromReference(reference, mode)
+    if mode == nil then
+      local status, b
+      for _, m in ipairs({'local', 'global', 'shared'}) do
+        status, b = pcall(Buffer.fromReference, reference, m)
+        if status then
+          return b
+        end
+      end
+    end
+    return getClassName(mode).fromReference(reference, mode)
+  end
+
+end)

jls/lang/Buffer-.lua → jls/lang/BufferFile.lua

@@ -1,12 +1,9 @@
 local class = require('jls.lang.class')
 
-return class.create(function(buffer)
+return class.create('jls.lang.Buffer', function(buffer)
 
   function buffer:initialize(size, name, preserve)
-    if math.type(size) ~= 'integer' or size <= 0 then
-      error('invalid size '..tostring(size))
-    end
-    self.size = size or 0
+    self.size = size
     self.name = name or string.format('.%s-%p.tmp', 'jls.lang.Buffer', self)
     self.file = assert(io.open(self.name, preserve and 'r+b' or 'w+b'))
     if not preserve then
@@ -63,19 +60,10 @@ return class.create(function(buffer)
     return self.name..'#'..tostring(self.size)
   end
 
-  function buffer:toString()
-    return self:get()
-  end
-
 end, function(Buffer)
 
-  function Buffer.allocate(sizeOrData)
-    if type(sizeOrData) == 'string' then
-      local buffer = Buffer:new(#sizeOrData)
-      buffer:set(sizeOrData)
-      return buffer
-    end
-    return Buffer:new(sizeOrData)
+  function Buffer.allocate(size)
+    return Buffer:new(size)
   end
 
   function Buffer.fromReference(reference)

jls/lang/BufferGlobal.lua

@@ -0,0 +1 @@
+return require('jls.lang.loader').requireOne('jls.lang.Buffer-buffer', 'jls.lang.BufferFile')

jls/lang/BufferLocal.lua

@@ -0,0 +1 @@
+return require('jls.lang.loader').requireOne('jls.lang.Buffer-buffer', 'jls.lang.BufferFile')

jls/lang/BufferShared.lua

@@ -0,0 +1 @@
+return require('jls.lang.BufferFile')

tests/full/Buffer.lua

@@ -10,7 +10,7 @@ end
 function Test_buffer_from_string()
   local buffer = Buffer.allocate('Hello')
   lu.assertEquals(buffer:length(), 5)
-  lu.assertEquals(buffer:toString(), 'Hello')
+  lu.assertEquals(buffer:get(), 'Hello')
 end
 
 function Test_buffer_bytes()

tests/full/thread_memory.lua

@@ -8,17 +8,17 @@ local loop = require('jls.lang.loopWithTimeout')
 
 -- Indicate to a polling thread that it must terminate
 function Test_thread_buffer()
-  local buffer = Buffer.allocate(1)
+  local buffer = Buffer.allocate(1, 'global')
   buffer:setBytes(1, 0)
   lu.assertEquals(buffer:getBytes(), 0)
   local result = nil
-  Thread:new(function(l)
-    local Mem = require('jls.lang.Buffer')
+  Thread:new(function(ref)
+    local Buf = require('jls.lang.Buffer')
     local sys = require('jls.lang.system')
-    local mem = Mem.fromReference(l, 1)
+    local buf = Buf.fromReference(ref, 'global')
     local n = 0
     while true do
-      local v = mem:getBytes()
+      local v = buf:getBytes()
       n = n + 1
       if v ~= 0 then
         return n
@@ -65,6 +65,7 @@ function Test_thread_lock()
   if not loop() then
     lu.fail('Timeout reached')
   end
+  lock:finalize()
   lu.assertNotNil(result)
   lu.assertEquals(result, 'tryLock=false')
   lu.assertTrue(ms >= 400) -- may fail