Add comprehensive documentation for Folly integration example

This adds a detailed README.md for the examples/folly directory that covers:
- Overview of Rust-Folly async interoperability
- Key components and architecture
- Feature demonstrations (parallel computation, exception handling, async streams)
- Build and run instructions
- Test coverage details
- Performance considerations

Closes #14

Author: Xuanwo

examples/folly/README.md

@@ -0,0 +1,192 @@
+# Folly Integration Example
+
+This example demonstrates how to use `cxx-async` to seamlessly integrate Rust async code with Facebook's [Folly](https://github.com/facebook/folly) C++ async framework.
+
+## Overview
+
+The example showcases bidirectional async interoperability between Rust and C++ using Folly coroutines and futures. It demonstrates various async patterns including:
+
+- Rust calling C++ async functions (using both Folly coroutines and futures)
+- C++ calling Rust async functions 
+- Exception/error handling across language boundaries
+- Async streams (generators) support
+- Complex async patterns like ping-pong communication
+
+## Key Components
+
+### Rust Side (`src/main.rs`)
+
+- **Bridge Definitions**: Uses `#[cxx::bridge]` and `#[cxx_async::bridge]` to define FFI bindings for async types
+- **Async Functions**: Implements Rust async functions that can be called from C++
+- **Test Suite**: Comprehensive tests covering various interop scenarios
+
+### C++ Side
+
+- **`include/folly_example.h`**: Header file defining the C++ async interface using `CXXASYNC_DEFINE_FUTURE` and `CXXASYNC_DEFINE_STREAM` macros
+- **`src/folly_example.cpp`**: Implementation using Folly coroutines (`folly::coro::Task`) and futures
+
+## Features Demonstrated
+
+### 1. Parallel Computation
+
+The example implements a parallel dot product calculation that:
+- Recursively splits the work when the array size exceeds a threshold
+- Spawns tasks on thread pools (both Rust and C++ sides)
+- Aggregates results asynchronously
+
+```cpp
+// C++ side using Folly coroutines
+static folly::coro::Task<double> do_dot_product_coro(const double a[], const double b[], size_t count) {
+    if (count > EXAMPLE_SPLIT_LIMIT) {
+        // Split and compute in parallel
+        auto [first, second] = co_await folly::collectAll(taskA, taskB);
+        co_return *first + *second;
+    }
+    // Base case: compute directly
+}
+```
+
+```rust
+// Rust side using async/await
+#[async_recursion]
+async fn dot_product(range: Range<usize>) -> f64 {
+    if len > SPLIT_LIMIT {
+        // Split and compute in parallel
+        let (first, second) = join!(/* ... */);
+        return first + second;
+    }
+    // Base case: compute directly
+}
+```
+
+### 2. Exception Handling
+
+Custom exception handling across the FFI boundary:
+
+```cpp
+// C++ custom exception
+class MyException : public std::exception {
+    const char* message() const noexcept;
+};
+
+// Template specialization for exception handling
+template <typename T>
+struct TryCatch<T, Custom> {
+    static void trycatch(Try&& func, Fail&& fail) noexcept {
+        try {
+            func();
+        } catch (const MyException& exception) {
+            fail(exception.message());
+        }
+    }
+};
+```
+
+### 3. Async Streams
+
+The example includes FizzBuzz implementations using async streams:
+
+```cpp
+// C++ generator coroutine
+RustStreamString folly_fizzbuzz() {
+    for (int i = 1; i <= 15; i++) {
+        if (i % 15 == 0) {
+            co_yield rust::String("FizzBuzz");
+        } else if (i % 5 == 0) {
+            co_yield rust::String("Buzz");
+        } // ...
+    }
+}
+```
+
+### 4. Ping-Pong Pattern
+
+Demonstrates multiple async calls across language boundaries:
+
+```rust
+// Rust side
+fn rust_folly_ping_pong(i: i32) -> RustFutureString {
+    RustFutureString::infallible(async move {
+        format!("{}ping ", 
+            if i < 4 {
+                ffi::folly_ping_pong(i + 1).await.unwrap()
+            } else {
+                "".to_owned()
+            })
+    })
+}
+```
+
+## Building and Running
+
+### Prerequisites
+
+- Folly library installed (the build uses `find-folly` crate)
+- C++20 compiler support
+- Rust toolchain
+
+### Build
+
+```bash
+cargo build --example folly
+```
+
+### Run Tests
+
+```bash
+cargo test --example folly
+```
+
+### Run Example
+
+```bash
+cargo run --example folly
+```
+
+## Test Coverage
+
+The example includes extensive tests for:
+
+- Synchronous calling patterns (Rust → C++, C++ → Rust)
+- Asynchronous execution on thread pools
+- Exception and error propagation
+- Void return types
+- Future dropping and cleanup
+- Stream operations with exceptions
+- Coroutine lifecycle management
+
+## Architecture Notes
+
+### Thread Pools
+
+- **C++ Side**: Uses `folly::CPUThreadPoolExecutor` with 8 threads
+- **Rust Side**: Uses `futures::executor::ThreadPool`
+
+### Memory Management
+
+The example demonstrates proper memory management:
+- Coroutines run to completion ensuring destructors are called
+- Futures can be safely dropped
+- Background tasks are properly managed through Folly's reaper
+
+### Type Mapping
+
+| Rust Type | C++ Type | Purpose |
+|-----------|----------|---------|
+| `RustFutureVoid` | `folly::coro::Task<void>` | Async operations without return value |
+| `RustFutureF64` | `folly::coro::Task<double>` | Async operations returning floating point |
+| `RustFutureString` | `folly::coro::Task<rust::String>` | Async operations returning strings |
+| `RustStreamString` | Generator coroutine | Async stream of strings |
+
+## Performance Considerations
+
+The example is designed to showcase real parallelism:
+- Work is distributed across multiple threads
+- Large arrays (16384 elements) ensure meaningful computation
+- Split threshold (32 elements) balances parallelism overhead
+
+## Further Reading
+
+- [Folly Documentation](https://github.com/facebook/folly/tree/main/folly/docs)
+- [cxx-async Documentation](https://github.com/pcwalton/cxx-async)
+- [CXX Documentation](https://cxx.rs/)