GH-38015: [MATLAB] Add arrow.buffer.Buffer class to the MATLAB Interface

matlab/src/cpp/arrow/matlab/buffer/proxy/buffer.cc

@@ -0,0 +1,96 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+
+#include "arrow/matlab/buffer/proxy/buffer.h"
+#include "arrow/matlab/buffer/matlab_buffer.h"
+#include "arrow/matlab/error/error.h"
+#include "libmexclass/proxy/ProxyManager.h"
+
+namespace arrow::matlab::buffer::proxy {
+
+    Buffer::Buffer(std::shared_ptr<arrow::Buffer> buffer) : buffer{std::move(buffer)} {
+        REGISTER_METHOD(Buffer, getNumBytes);
+        REGISTER_METHOD(Buffer, isEqual);
+        REGISTER_METHOD(Buffer, toMATLAB);
+    }
+
+    libmexclass::proxy::MakeResult Buffer::make(const libmexclass::proxy::FunctionArguments& constructor_arguments) {
+        namespace mda = ::matlab::data;
+        using BufferProxy = proxy::Buffer;
+        using MatlabBuffer = arrow::matlab::buffer::MatlabBuffer;
+
+        mda::StructArray opts = constructor_arguments[0];
+        const mda::TypedArray<uint8_t> values_mda = opts[0]["Values"];
+        auto buffer = std::make_shared<MatlabBuffer>(values_mda);
+        return std::make_shared<BufferProxy>(std::move(buffer));
+    }
+
+    std::shared_ptr<arrow::Buffer> Buffer::unwrap() {
+        return buffer;
+    }
+
+    void Buffer::getNumBytes(libmexclass::proxy::method::Context& context) {
+        namespace mda = ::matlab::data;
+        mda::ArrayFactory factory;        
+        auto num_bytes_mda = factory.createScalar(buffer->size());
+        context.outputs[0] = num_bytes_mda; 
+    }
+
+    void Buffer::isEqual(libmexclass::proxy::method::Context& context) { 
+        namespace mda = ::matlab::data;
+
+        bool is_equal = true;
+        const mda::TypedArray<uint64_t> buffer_proxy_ids = context.inputs[0];
+        for (const auto& buffer_proxy_id : buffer_proxy_ids) {
+            // Retrieve the Buffer proxy from the ProxyManager
+            auto proxy = libmexclass::proxy::ProxyManager::getProxy(buffer_proxy_id);
+            auto buffer_proxy = std::static_pointer_cast<proxy::Buffer>(proxy);
+            auto buffer_to_compare = buffer_proxy->unwrap();
+
+            if (!buffer->Equals(*buffer_to_compare)) {
+                is_equal = false;
+                break;
+            }
+        }
+        mda::ArrayFactory factory;
+        context.outputs[0] = factory.createScalar(is_equal);
+    }
+
+    void Buffer::toMATLAB(libmexclass::proxy::method::Context& context) { 
+        namespace mda = ::matlab::data;
+
+        // If buffer->is_cpu() returns false, invoking buffer->data() may cause a crash.
+        // Avoid this potential crash by first invoking ViewOrCopy(buffer, memory_manager_device).
+        // This function tries to create a no-copy view of the buffer on the given memory
+        // manager device. If not possible, then ViewOrCopy copies the buffer's contents.
+        MATLAB_ASSIGN_OR_ERROR_WITH_CONTEXT(
+            auto cpu_buffer, 
+            arrow::Buffer::ViewOrCopy(buffer, arrow::default_cpu_memory_manager()),
+            context, error::BUFFER_VIEW_OR_COPY_FAILED
+        );
+
+        const auto* data_begin = cpu_buffer->data();
+        const auto num_bytes = cpu_buffer->size();
+        // data_begin is a uint8_t*, so num_bytes is equal to the number of elements
+        const auto* data_end = data_begin + num_bytes;
+
+        mda::ArrayFactory factory;
+        context.outputs[0] = factory.createArray<uint8_t>({static_cast<size_t>(num_bytes), 1}, data_begin, data_end);
+    }
+
+}

matlab/src/cpp/arrow/matlab/buffer/proxy/buffer.h

@@ -0,0 +1,46 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+#pragma once
+
+#include "arrow/buffer.h"
+
+#include "libmexclass/proxy/Proxy.h"
+
+namespace arrow::matlab::buffer::proxy {
+
+class Buffer : public libmexclass::proxy::Proxy {
+    public:
+        Buffer(std::shared_ptr<arrow::Buffer> buffer);
+
+        ~Buffer() {}
+
+        std::shared_ptr<arrow::Buffer> unwrap();
+
+        static libmexclass::proxy::MakeResult make(const libmexclass::proxy::FunctionArguments& constructor_arguments);
+
+    protected:
+        void getNumBytes(libmexclass::proxy::method::Context& context);
+
+        void toMATLAB(libmexclass::proxy::method::Context& context);
+
+        void isEqual(libmexclass::proxy::method::Context& context);
+
+        std::shared_ptr<arrow::Buffer> buffer;
+};
+
+}

matlab/src/cpp/arrow/matlab/error/error.h

@@ -198,4 +198,5 @@ namespace arrow::matlab::error {
     static const char* STRUCT_ARRAY_MAKE_FAILED = "arrow:array:StructArrayMakeFailed";
     static const char* INDEX_EMPTY_CONTAINER = "arrow:index:EmptyContainer";
     static const char* INDEX_OUT_OF_RANGE = "arrow:index:OutOfRange";
+    static const char* BUFFER_VIEW_OR_COPY_FAILED = "arrow:buffer:ViewOrCopyFailed";
 }

matlab/src/cpp/arrow/matlab/proxy/factory.cc

@@ -40,6 +40,7 @@
 #include "arrow/matlab/io/feather/proxy/reader.h"
 #include "arrow/matlab/io/csv/proxy/table_writer.h"
 #include "arrow/matlab/io/csv/proxy/table_reader.h"
+#include "arrow/matlab/buffer/proxy/buffer.h"
 
 #include "factory.h"
 
@@ -65,6 +66,7 @@ libmexclass::proxy::MakeResult Factory::make_proxy(const ClassName& class_name,
     REGISTER_PROXY(arrow.array.proxy.Date32Array   , arrow::matlab::array::proxy::NumericArray<arrow::Date32Type>);
     REGISTER_PROXY(arrow.array.proxy.Date64Array   , arrow::matlab::array::proxy::NumericArray<arrow::Date64Type>);
     REGISTER_PROXY(arrow.array.proxy.ChunkedArray  , arrow::matlab::array::proxy::ChunkedArray);
+    REGISTER_PROXY(arrow.buffer.proxy.Buffer       , arrow::matlab::buffer::proxy::Buffer);
     REGISTER_PROXY(arrow.tabular.proxy.RecordBatch , arrow::matlab::tabular::proxy::RecordBatch);
     REGISTER_PROXY(arrow.tabular.proxy.Table       , arrow::matlab::tabular::proxy::Table);
     REGISTER_PROXY(arrow.tabular.proxy.Schema      , arrow::matlab::tabular::proxy::Schema);

matlab/src/matlab/+arrow/+buffer/Buffer.m

@@ -0,0 +1,81 @@
+%BUFFER Represents a block of contiguous memory with a specified size.
+
+% Licensed to the Apache Software Foundation (ASF) under one or more
+% contributor license agreements.  See the NOTICE file distributed with
+% this work for additional information regarding copyright ownership.
+% The ASF licenses this file to you under the Apache License, Version
+% 2.0 (the "License"); you may not use this file except in compliance
+% with the License.  You may obtain a copy of the License at
+%
+%   http://www.apache.org/licenses/LICENSE-2.0
+%
+% Unless required by applicable law or agreed to in writing, software
+% distributed under the License is distributed on an "AS IS" BASIS,
+% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+% implied.  See the License for the specific language governing
+% permissions and limitations under the License.
+
+classdef Buffer < matlab.mixin.Scalar
+
+    properties (Dependent, GetAccess=public, SetAccess=private)
+        NumBytes
+    end
+
+    properties (Hidden, GetAccess=public, SetAccess=private)
+        Proxy
+    end
+
+    methods
+        function obj = Buffer(proxy)
+            arguments
+                proxy(1, 1) libmexclass.proxy.Proxy {validate(proxy, "arrow.buffer.proxy.Buffer")}
+            end
+            import arrow.internal.proxy.validate
+            obj.Proxy = proxy;
+        end
+
+        function numBytes = get.NumBytes(obj)
+            numBytes = obj.Proxy.getNumBytes();
+        end
+
+        function data = toMATLAB(obj)
+            data = obj.Proxy.toMATLAB();
+        end
+
+        function tf = isequal(obj, varargin)
+            narginchk(2, inf);
+            tf = false;
+
+            bufferProxyIDs = zeros([1 numel(varargin)], "uint64");
+            for ii = 1:numel(varargin)
+                maybeBuffer = varargin{ii};
+                if ~isa(maybeBuffer, "arrow.buffer.Buffer")
+                    % If maybeBuffer is not an instance of
+                    % arrow.buffer.Buffer, return false early.
+                    return;
+                end
+                % Otherwise, extract the proxy ID associated with
+                % maybeBuffer.
+                bufferProxyIDs(ii) = maybeBuffer.Proxy.ID;
+            end
+
+            % Invoke the isEqual method on the Buffer Proxy class.
+            tf = obj.Proxy.isEqual(bufferProxyIDs);
+        end
+    end
+
+    methods (Static, Hidden)
+        function buffer = fromMATLAB(data)
+            arguments
+                data(:, 1) {mustBeNumeric, mustBeNonsparse, mustBeReal}
+            end
+
+            % Re-interpret bit pattern as uint8s without changing the
+            % underlying data.
+            data = typecast(data, "uint8");
+            args = struct(Values=data);
+            proxy = arrow.internal.proxy.create("arrow.buffer.proxy.Buffer", args);
+            buffer = arrow.buffer.Buffer(proxy);
+        end
+    end
+end