ARROW-13185: [MATLAB] Create a single MEX gateway function which delegates to specific C++ functions

.github/workflows/matlab.yml

@@ -60,6 +60,10 @@ jobs:
           # errors will occur. To work around this issue, we can explicitly
           # force MATLAB to use the system libstdc++.so via LD_PRELOAD.
           LD_PRELOAD: /usr/lib/x86_64-linux-gnu/libstdc++.so.6
+
+          # Add the installation directory to the MATLAB Search Path by
+          # setting the MATLABPATH environment variable.
+          MATLABPATH: matlab/install/arrow_matlab
         uses: matlab-actions/run-tests@v1
         with:
           select-by-folder: matlab/test

ci/scripts/matlab_build.sh

@@ -23,7 +23,8 @@ set -ex
 base_dir=${1}
 source_dir=${base_dir}/matlab
 build_dir=${base_dir}/matlab/build
+install_dir=${base_dir}/matlab/install
 
-cmake -S ${source_dir} -B ${build_dir} -G Ninja -D MATLAB_BUILD_TESTS=ON
-cmake --build ${build_dir} --config Release
+cmake -S ${source_dir} -B ${build_dir} -G Ninja -D MATLAB_BUILD_TESTS=ON -D CMAKE_INSTALL_PREFIX=${install_dir} -D MATLAB_ADD_INSTALL_DIR_TO_SEARCH_PATH=OFF
+cmake --build ${build_dir} --config Release --target install
 ctest --test-dir ${build_dir}

matlab/src/cpp/arrow/matlab/api/visibility.h

@@ -0,0 +1,28 @@
+// 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
+
+#if defined(_WIN32) || defined(__CYGWIN__)
+#ifdef ARROW_MATLAB_EXPORTING
+#define ARROW_MATLAB_EXPORT __declspec(dllexport)
+#else
+#define ARROW_MATLAB_EXPORT __declspec(dllimport)
+#endif
+#else // Not Windows
+#define ARROW_MATLAB_EXPORT __attribute__((visibility("default")))
+#endif

matlab/src/cpp/arrow/matlab/feather/feather_functions.cc

@@ -0,0 +1,55 @@
+// 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 "feather_functions.h"
+
+#include <string>
+
+#include "feather_reader.h"
+#include "feather_writer.h"
+#include "util/handle_status.h"
+
+namespace arrow {
+namespace matlab {
+namespace feather {
+
+void featherwrite(int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[]) {
+  const std::string filename{mxArrayToUTF8String(prhs[0])};
+
+  // Open a Feather file at the provided file path for writing.
+  std::shared_ptr<FeatherWriter> feather_writer{nullptr};
+  util::HandleStatus(FeatherWriter::Open(filename, &feather_writer));
+
+  // Write the Feather file table variables and table metadata from MATLAB.
+  util::HandleStatus(feather_writer->WriteVariables(prhs[1], prhs[2]));
+}
+
+void featherread(int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[]) {
+  const std::string filename{mxArrayToUTF8String(prhs[0])};
+
+  // Read the given Feather file into memory.
+  std::shared_ptr<FeatherReader> feather_reader{nullptr};
+  util::HandleStatus(FeatherReader::Open(filename, &feather_reader));
+
+  // Return the Feather file table variables and table metadata to MATLAB.
+  plhs[0] = feather_reader->ReadVariables();
+  plhs[1] = feather_reader->ReadMetadata();
+}
+
+}  // namespace feather
+}  // namespace matlab
+}  // namespace arrow

matlab/src/cpp/arrow/matlab/feather/feather_functions.h

@@ -0,0 +1,34 @@
+// 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 <mex.h>
+
+#include "arrow/matlab/api/visibility.h"
+
+namespace arrow {
+namespace matlab {
+namespace feather {
+
+ARROW_MATLAB_EXPORT void featherwrite(int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[]);
+
+ARROW_MATLAB_EXPORT void featherread(int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[]);
+
+}  // namespace feather
+}  // namespace matlab
+}  // namespace arrow

matlab/src/feather_reader.cc → matlab/src/cpp/arrow/matlab/feather/feather_reader.cc

@@ -15,9 +15,6 @@
 // specific language governing permissions and limitations
 // under the License.
 
-#include <algorithm>
-#include <cmath>
-
 #include "feather_reader.h"
 
 #include <arrow/array/array_base.h>
@@ -33,17 +30,21 @@
 #include <arrow/util/bitmap_visit.h>
 #include <mex.h>
 
+#include <algorithm>
+#include <cmath>
+
 #include "matlab_traits.h"
 #include "util/handle_status.h"
 #include "util/unicode_conversion.h"
 
 namespace arrow {
 namespace matlab {
+namespace feather {
 namespace internal {
 
 // Read the name of variable i from the Feather file as a mxArray*.
 mxArray* ReadVariableName(const std::string& column_name) {
-  return matlab::util::ConvertUTF8StringToUTF16CharMatrix(column_name);
+  return util::ConvertUTF8StringToUTF16CharMatrix(column_name);
 }
 
 template <typename ArrowDataType>
@@ -57,8 +58,7 @@ mxArray* ReadNumericVariableData(const std::shared_ptr<Array>& column) {
   mxArray* variable_data =
       mxCreateNumericMatrix(column->length(), 1, matlab_class_id, mxREAL);
 
-  auto arrow_numeric_array =
-      std::static_pointer_cast<ArrowArrayType>(column);
+  auto arrow_numeric_array = std::static_pointer_cast<ArrowArrayType>(column);
 
   // Get a raw pointer to the Arrow array data.
   const MatlabType* source = arrow_numeric_array->raw_values();
@@ -182,10 +182,10 @@ Status FeatherReader::Open(const std::string& filename,
 
   // Open file with given filename as a ReadableFile.
   ARROW_ASSIGN_OR_RAISE(auto readable_file, io::ReadableFile::Open(filename));
- 
+
   // Open the Feather file for reading with a TableReader.
   ARROW_ASSIGN_OR_RAISE(auto reader, ipc::feather::Reader::Open(readable_file));
- 
+
   // Set the internal reader_ object.
   (*feather_reader)->reader_ = reader;
 
@@ -273,5 +273,6 @@ mxArray* FeatherReader::ReadVariables() {
   return variables;
 }
 
+}  // namespace feather
 }  // namespace matlab
-}  // namespace arrow
+}  // namespace arrow

matlab/src/feather_reader.h → matlab/src/cpp/arrow/matlab/feather/feather_reader.h

@@ -17,16 +17,17 @@
 
 #pragma once
 
-#include <memory>
-#include <string>
-
 #include <arrow/ipc/feather.h>
 #include <arrow/status.h>
 #include <arrow/type.h>
 #include <matrix.h>
 
+#include <memory>
+#include <string>
+
 namespace arrow {
 namespace matlab {
+namespace feather {
 
 class FeatherReader {
  public:
@@ -71,5 +72,6 @@ class FeatherReader {
   std::string description_;
 };
 
+}  // namespace feather
 }  // namespace matlab
-}  // namespace arrow
+}  // namespace arrow

matlab/src/feather_writer.cc → matlab/src/cpp/arrow/matlab/feather/feather_writer.cc

@@ -15,10 +15,6 @@
 // specific language governing permissions and limitations
 // under the License.
 
-#include <cmath>
-#include <functional> /* for std::multiplies */
-#include <numeric>    /* for std::accumulate */
-
 #include "feather_writer.h"
 
 #include <arrow/array.h>
@@ -33,11 +29,16 @@
 #include <arrow/util/key_value_metadata.h>
 #include <mex.h>
 
+#include <cmath>
+#include <functional> /* for std::multiplies */
+#include <numeric>    /* for std::accumulate */
+
 #include "matlab_traits.h"
 #include "util/handle_status.h"
 
 namespace arrow {
 namespace matlab {
+namespace feather {
 namespace internal {
 
 // Returns the arrow::DataType that corresponds to the input type string
@@ -279,7 +280,8 @@ Status FeatherWriter::Open(const std::string& filename,
   *feather_writer = std::shared_ptr<FeatherWriter>(new FeatherWriter());
 
   // Open a FileOutputStream corresponding to the provided filename.
-  ARROW_ASSIGN_OR_RAISE((*feather_writer)->file_output_stream_,
+  ARROW_ASSIGN_OR_RAISE(
+      (*feather_writer)->file_output_stream_,
       io::FileOutputStream::Open(filename, &((*feather_writer)->file_output_stream_)));
   return Status::OK();
 }
@@ -331,15 +333,15 @@ Status FeatherWriter::WriteVariables(const mxArray* variables, const mxArray* me
     auto datatype = internal::ConvertMatlabTypeStringToArrowDataType(type_str);
     auto field = std::make_shared<arrow::Field>(name_str, datatype);
 
-    ARROW_ASSIGN_OR_RAISE(std::shared_ptr<ResizableBuffer> validity_bitmap,
+    ARROW_ASSIGN_OR_RAISE(
+        std::shared_ptr<ResizableBuffer> validity_bitmap,
         arrow::AllocateResizableBuffer(internal::BitPackedLength(num_rows_)));
 
     // Populate bit-packed arrow::Buffer using validity data in the mxArray*.
     internal::BitPackBuffer(valid, validity_bitmap);
 
     // Wrap mxArray data in an arrow::Array of the equivalent type.
-    auto array =
-        internal::WriteVariableData(data, type_str, validity_bitmap);
+    auto array = internal::WriteVariableData(data, type_str, validity_bitmap);
 
     // Verify that the arrow::Array has the right number of elements.
     internal::ValidateNumRows(array->length(), num_rows_);
@@ -362,5 +364,6 @@ Status FeatherWriter::WriteVariables(const mxArray* variables, const mxArray* me
   return ipc::feather::WriteTable(*table, file_output_stream_.get(), write_props);
 }
 
+}  // namespace feather
 }  // namespace matlab
 }  // namespace arrow

matlab/src/feather_writer.h → matlab/src/cpp/arrow/matlab/feather/feather_writer.h

@@ -17,16 +17,17 @@
 
 #pragma once
 
-#include <memory>
-#include <string>
-
 #include <arrow/ipc/feather.h>
 #include <arrow/status.h>
 #include <arrow/type.h>
 #include <matrix.h>
 
+#include <memory>
+#include <string>
+
 namespace arrow {
 namespace matlab {
+namespace feather {
 
 class FeatherWriter {
  public:
@@ -64,5 +65,6 @@ class FeatherWriter {
   std::shared_ptr<arrow::io::OutputStream> file_output_stream_;
 };
 
+}  // namespace feather
 }  // namespace matlab
-}  // namespace arrow
+}  // namespace arrow

matlab/src/matlab_traits.h → matlab/src/cpp/arrow/matlab/feather/matlab_traits.h

@@ -18,7 +18,6 @@
 #pragma once
 
 #include <arrow/type.h>
-
 #include <matrix.h>
 
 namespace arrow {
@@ -100,4 +99,3 @@ struct MatlabTraits<Int64Type> {
 
 }  // namespace matlab
 }  // namespace arrow
-

matlab/src/util/handle_status.cc → matlab/src/cpp/arrow/matlab/feather/util/handle_status.cc

@@ -16,11 +16,11 @@
 // under the License.
 
 #include <arrow/status.h>
-
 #include <mex.h>
 
 namespace arrow {
 namespace matlab {
+namespace feather {
 namespace util {
 
 void HandleStatus(const Status& status) {
@@ -86,6 +86,8 @@ void HandleStatus(const Status& status) {
     }
   }
 }
+
 }  // namespace util
+}  // namespace feather
 }  // namespace matlab
 }  // namespace arrow

matlab/src/util/handle_status.h → matlab/src/cpp/arrow/matlab/feather/util/handle_status.h

@@ -21,12 +21,15 @@
 
 namespace arrow {
 namespace matlab {
+namespace feather {
 namespace util {
+
 // Terminates execution and returns to the MATLAB prompt,
 // displaying an error message if the given status
 // indicates that an error has occurred.
 void HandleStatus(const Status& status);
+
 }  // namespace util
+}  // namespace feather
 }  // namespace matlab
 }  // namespace arrow
-