Add Target Feature Recommendations to Arrow Crate Docs

arrow/src/lib.rs

@@ -18,6 +18,42 @@
 //! A complete, safe, native Rust implementation of [Apache Arrow](https://arrow.apache.org), a cross-language
 //! development platform for in-memory data.
 //!
+//! # Performance Tips
+//!
+//! Arrow aims to be as fast as possible out of the box, whilst not compromising on safety. However,
+//! it relies heavily on LLVM auto-vectorisation to achieve this. Unfortunately the LLVM defaults,
+//! particularly for x86_64, favour portability over performance, and LLVM will consequently avoid
+//! using more recent instructions that would result in errors on older CPUs.
+//!
+//! To address this it is recommended that you specify the override the LLVM defaults either
+//! by setting the `RUSTFLAGS` environment variable, or by setting `rustflags` in your
+//! [Cargo configuration](https://doc.rust-lang.org/cargo/reference/config.html)
+//!
+//! Enable all features supported by the current CPU
+//!
+//! ```ignore
+//! RUSTFLAGS="-C target-cpu=native"
+//! ```
+//!
+//! Enable all features supported by the current CPU, and enable full use of AVX512
+//!
+//! ```ignore
+//! RUSTFLAGS="-C target-cpu=native -C target-feature=-prefer-256-bit"
+//! ```
+//!
+//! Enable all features supported by CPUs more recent than haswell (2013)
+//!
+//! ```ignore
+//! RUSTFLAGS="-C target-cpu=haswell"
+//! ```
+//!
+//! For a full list of features and target CPUs use
+//!
+//! ```ignore
+//! $ rustc --print target-cpus
+//! $ rustc --print target-features
+//! ```
+//!
 //! # Columnar Format
 //!
 //! The [`array`] module provides statically typed implementations of all the array
@@ -57,6 +93,23 @@
 //! assert_eq!(sum(&TimestampNanosecondArray::from(vec![1, 2, 3])), 6);
 //! ```
 //!
+//! And the following is generic over all arrays with comparable values
+//!
+//! ```rust
+//! # use arrow::array::{ArrayAccessor, ArrayIter, Int32Array, StringArray};
+//! # use arrow::datatypes::ArrowPrimitiveType;
+//! #
+//! fn min<T: ArrayAccessor>(array: T) -> Option<T::Item>
+//! where
+//!     T::Item: Ord
+//! {
+//!     ArrayIter::new(array).filter_map(|v| v).min()
+//! }
+//!
+//! assert_eq!(min(&Int32Array::from(vec![4, 2, 1, 6])), Some(1));
+//! assert_eq!(min(&StringArray::from(vec!["b", "a", "c"])), Some("a"));
+//! ```
+//!
 //! For more examples, consult the [`array`] docs.
 //!
 //! # Type Erasure / Trait Objects