From b8d2924589afe16756a6ccd79dd995b6eb4a6121 Mon Sep 17 00:00:00 2001
From: Ruihang Xia <waynestxia@gmail.com>
Date: Mon, 2 Sep 2024 14:47:56 +0800
Subject: [PATCH] add document and example

Signed-off-by: Ruihang Xia <waynestxia@gmail.com>
---
 arrow-buffer/src/buffer/mutable.rs |  7 +++++
 arrow/Cargo.toml                   |  5 ++++
 arrow/README.md                    |  1 +
 arrow/examples/allocator_api.rs    | 43 ++++++++++++++++++++++++++++++
 4 files changed, 56 insertions(+)
 create mode 100644 arrow/examples/allocator_api.rs

diff --git a/arrow-buffer/src/buffer/mutable.rs b/arrow-buffer/src/buffer/mutable.rs
index 8ef97519c357..fdb6053a4303 100644
--- a/arrow-buffer/src/buffer/mutable.rs
+++ b/arrow-buffer/src/buffer/mutable.rs
@@ -72,6 +72,13 @@ mod private {
 /// let buffer: Buffer = buffer.into();
 /// assert_eq!(buffer.as_slice(), &[0u8, 1, 0, 0, 1, 0, 0, 0])
 /// ```
+///
+/// # Customize [`Allocator`]
+///
+/// To customize the allocator for the buffer, enable the `allocator_api` feature and use either
+/// methods like [`MutableBuffer::new_in`] or [`MutableBuffer::with_capacity_in`], or inherit the
+/// allocator from a type like [`Vec`] using [`MutableBuffer::from`]. A example can be found in
+/// the [allocator_api example](https://github.com/apache/arrow-rs/tree/master/arrow/examples).
 #[derive(Debug)]
 pub struct MutableBuffer<
     #[cfg(feature = "allocator_api")] A: Allocator = Global,
diff --git a/arrow/Cargo.toml b/arrow/Cargo.toml
index a0fd96415a1d..e18f2cae8ebb 100644
--- a/arrow/Cargo.toml
+++ b/arrow/Cargo.toml
@@ -81,6 +81,7 @@ force_validate = ["arrow-array/force_validate", "arrow-data/force_validate"]
 # Enable ffi support
 ffi = ["arrow-schema/ffi", "arrow-data/ffi", "arrow-array/ffi"]
 chrono-tz = ["arrow-array/chrono-tz"]
+allocator_api = ["arrow-buffer/allocator_api"]
 
 [dev-dependencies]
 chrono = { workspace = true }
@@ -107,6 +108,10 @@ name = "read_csv_infer_schema"
 required-features = ["prettyprint", "csv"]
 path = "./examples/read_csv_infer_schema.rs"
 
+[[example]]
+name = "allocator_api"
+path = "./examples/allocator_api.rs"
+
 [[bench]]
 name = "aggregate_kernels"
 harness = false
diff --git a/arrow/README.md b/arrow/README.md
index 557a0b474e4b..7daf2c408295 100644
--- a/arrow/README.md
+++ b/arrow/README.md
@@ -61,6 +61,7 @@ The `arrow` crate provides the following features which may be enabled in your `
 - `chrono-tz` - support of parsing timezone using [chrono-tz](https://docs.rs/chrono-tz/0.6.0/chrono_tz/)
 - `ffi` - bindings for the Arrow C [C Data Interface](https://arrow.apache.org/docs/format/CDataInterface.html)
 - `pyarrow` - bindings for pyo3 to call arrow-rs from python
+- `allocator_api` - support for customizing memory [`Allocator`](https://doc.rust-lang.org/std/alloc/trait.Allocator.html) for underlying Array [`MutableBuffer`](https://docs.rs/arrow/latest/arrow/buffer/struct.MutableBuffer.html). This feature requires a nightly rust toolchain.
 
 ## Arrow Feature Status
 
diff --git a/arrow/examples/allocator_api.rs b/arrow/examples/allocator_api.rs
new file mode 100644
index 000000000000..3ca18d8dda57
--- /dev/null
+++ b/arrow/examples/allocator_api.rs
@@ -0,0 +1,43 @@
+// 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.
+
+//! Customizing [`Allocator`] for Arrow Array's underlying [`MutableBuffer`].
+//!
+//! This module requires the `allocator_api` feature and a nightly channel Rust toolchain.
+
+fn main() {
+    demo();
+}
+
+#[cfg(not(feature = "allocator_api"))]
+fn demo() {
+    println!("This example requires the `allocator_api` feature to be enabled.");
+}
+
+#[cfg(feature = "allocator_api")]
+fn demo() {
+    use arrow::buffer::MutableBuffer;
+    use std::alloc::Global;
+
+    // Creates a mutable buffer with customized allocator
+    let mut buffer = MutableBuffer::<u8>::with_capacity_in(10, Global);
+
+    // Inherits allocator from Vec
+    let vector = Vec::<u8>::with_capacity_in(100, Global);
+    let mut buffer = MutableBuffer::from(vector);
+    buffer.reserve(100);
+}