Pingora Proxy

https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/
Admin
Pingora Proxy is a programmable HTTP proxy built on top of Pingora Core, offering HTTP/1.x and...
Tokens:37,397
Snippets:858
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### HttpProxy::new example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/struct.HttpProxy.html

Example of creating a new HttpProxy instance.

```rust
use pingora_proxy::HttpProxy;
use std::sync::Arc;

let mut proxy = HttpProxy::new(my_proxy_app, server_conf);
proxy.handle_init_modules();
let proxy = Arc::new(proxy);
// Use proxy.process_new_http() in your custom accept loop
```

--------------------------------

### Example for `AsFd` trait implementation on `Arc`

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

This example demonstrates how to implement traits that require `AsFd` on `Arc` by providing an example with `UdpSocket`.

```rust
use std::net::UdpSocket;
use std::sync::Arc;

trait MyTrait: AsFd {} 
impl MyTrait for Arc<UdpSocket> {}
impl MyTrait for Box<UdpSocket> {}
```

--------------------------------

### into_raw Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of consuming an Arc and returning the wrapped pointer.

```Rust
use std::sync::Arc;

let x = Arc::new("hello".to_owned());
let x_ptr = Arc::into_raw(x);
assert_eq!(unsafe { &*x_ptr }, "hello");

```

--------------------------------

### Arc::into_raw_with_allocator and Arc::from_raw_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates consuming an Arc to get the raw pointer and allocator, and then reconstructing the Arc.

```Rust
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;

let x = Arc::new_in("hello".to_owned(), System);
let (ptr, alloc) = Arc::into_raw_with_allocator(x);
assert_eq!(unsafe { &*ptr }, "hello");
let x = unsafe { Arc::from_raw_in(ptr, alloc) };
assert_eq!(&*x, "hello");

```

--------------------------------

### from_raw Example 1

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of converting a raw pointer back to an Arc<T>.

```Rust
use std::sync::Arc;

let x = Arc::new("hello".to_owned());
let x_ptr = Arc::into_raw(x);

unsafe {
    // Convert back to an `Arc` to prevent leak.
    let x = Arc::from_raw(x_ptr);
    assert_eq!(&*x, "hello");

    // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.
}

// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!

```

--------------------------------

### Arc::new_uninit_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of constructing an Arc with uninitialized contents using a specific allocator, followed by deferred initialization.

```rust
#![feature(get_mut_unchecked)]
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let mut five = Arc::<u32, _>::new_uninit_in(System);

let five = unsafe {
    // Deferred initialization:
    Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5)
```

--------------------------------

### Arc::new

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of creating a new Arc.

```rust
use std::sync::Arc;

let five = Arc::new(5);

```

--------------------------------

### Arc::new_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of constructing a new Arc with a specific allocator.

```rust
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let five = Arc::new_in(5, System);
```

--------------------------------

### as_ptr example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Demonstrates the usage of `Box::as_ptr` and `Box::as_mut_ptr` with aliasing guarantees.

```Rust
#![feature(box_as_ptr)]

unsafe {
    let mut v = Box::new(0);
    let ptr1 = Box::as_ptr(&v);
    let ptr2 = Box::as_mut_ptr(&mut v);
    let _val = ptr2.read();
    // No write to this memory has happened yet, so `ptr1` is still valid.
    let _val = ptr1.read();
    // However, once we do a write...
    ptr2.write(1);
    // ... `ptr1` is no longer valid.
    // This would be UB: let _val = ptr1.read();
}
```

--------------------------------

### Box::from_raw Example 2

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Manually creates a Box from scratch using the global allocator.

```Rust
use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw(ptr);
}

```

--------------------------------

### try_clone_from_ref Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example usage of try_clone_from_ref for Arc<T>.

```Rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::sync::Arc;

let hello: Arc<str> = Arc::try_clone_from_ref("hello")?;

```

--------------------------------

### new_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example of allocating memory using a specific allocator and placing a value into it.

```Rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::new_in(5, System);
```

--------------------------------

### try_new_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example of attempting to allocate memory and place a value, handling potential allocation errors.

```Rust
#![feature(allocator_api)]

use std::alloc::System;

let five = Box::try_new_in(5, System)?;
```

--------------------------------

### clone_from_ref Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example usage of clone_from_ref for Arc<T>.

```Rust
#![feature(clone_from_ref)]
use std::sync::Arc;

let hello: Arc<str> = Arc::clone_from_ref("hello");

```

--------------------------------

### Creating a pinned Box

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example demonstrating the use of Box::pin to construct a Pin<Box<T>>.

```Rust
let x = Box::new(7);
let pinned_box = Box::pin(x);
```

--------------------------------

### Box::from_non_null Example 2

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Manually creates a Box from scratch using the global allocator and NonNull.

```Rust
#![feature(box_vec_non_null)]

use std::alloc::{alloc, Layout};
use std::ptr::NonNull;

unsafe {
    let non_null = NonNull::new(alloc(Layout::new::<i32>()).cast::<i32>())
        .expect("allocation failed");
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `non_null`.
    non_null.write(5);
    let x = Box::from_non_null(non_null);
}

```

--------------------------------

### Arc::new_zeroed_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of constructing an Arc with zeroed memory using a specific allocator.

```rust
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let zero = Arc::<u32, _>::new_zeroed_in(System);
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### Arc::new_uninit

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of creating a new Arc with uninitialized contents and deferred initialization.

```rust
use std::sync::Arc;

let mut five = Arc::<u32>::new_uninit();

// Deferred initialization:
Arc::get_mut(&mut five).unwrap().write(5);

let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)

```

--------------------------------

### new_uninit_in Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Constructs a new box with uninitialized contents in the provided allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::new_uninit_in(System);
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

--------------------------------

### try_new_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates constructing a new `Arc<T, A>` in a provided allocator, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let five = Arc::try_new_in(5, System)?;
```

--------------------------------

### Box::into_raw Example 3

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Equivalent manual cleanup of Box::into_raw using Box::from_raw.

```Rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    drop(Box::from_raw(ptr));
}

```

--------------------------------

### try_new_uninit_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Shows constructing an `Arc` with uninitialized contents in a given allocator, handling potential allocation failures.

```rust
#![feature(allocator_api)]
#![feature(get_mut_unchecked)]

use std::sync::Arc;
use std::alloc::System;

let mut five = Arc::<u32, _>::try_new_uninit_in(System)?;

let five = unsafe {
    // Deferred initialization:
    Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5);
```

--------------------------------

### Creating a Box with a value

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Basic example of allocating memory on the heap and placing a value into it using Box::new.

```Rust
let five = Box::new(5);
```

--------------------------------

### Example Usage

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/fn.http_proxy.html

Example of creating and using HttpProxy in a custom accept loop with SNI routing.

```rust
use pingora_proxy::http_proxy;
use std::sync::Arc;

// Create the proxy
let proxy = Arc::new(http_proxy(&server_conf, my_proxy_app));

// In your custom accept loop:
loop {
    let (stream, addr) = listener.accept().await?;

    // Peek SNI, decide routing...
    if should_terminate_tls {
        let tls_stream = my_acceptor.accept(stream).await?;
        let session = HttpSession::new_http1(Box::new(tls_stream));
        proxy.process_new_http(session, &shutdown).await;
    }
}

```

--------------------------------

### try_new_uninit_in Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Constructs a new box with uninitialized contents in the provided allocator, returning an error if the allocation fails.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::try_new_uninit_in(System)?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

--------------------------------

### Trying to create a Box with uninitialized contents

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example using the experimental Box::try_new_uninit function to construct a Box with uninitialized contents, handling potential allocation errors.

```Rust
#![feature(allocator_api)]

let mut five = Box::<u32>::try_new_uninit()?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

--------------------------------

### from_raw Example 2

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of converting a raw pointer of a slice back to its original array type Arc.

```Rust
use std::sync::Arc;

let x: Arc<[u32]> = Arc::new([1, 2, 3]);
let x_ptr: *const [u32] = Arc::into_raw(x);

unsafe {
    let x: Arc<[u32; 3]> = Arc::from_raw(x_ptr.cast::<[u32; 3]>());
    assert_eq!(&*x, &[1, 2, 3]);
}

```

--------------------------------

### Arc::map example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates mapping a value inside an Arc, reusing the allocation if possible.

```Rust
#![feature(smart_pointer_try_map)]

use std::sync::Arc;

let r = Arc::new(7);
let new = Arc::map(r, |i| i + 7);
assert_eq!(*new, 14);

```

--------------------------------

### Aliasing guarantee example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example demonstrating the aliasing guarantee of Box::as_mut_ptr, showing that writes through one mutable pointer do not invalidate another mutable pointer to the same Box's contents.

```rust
#![feature(box_as_ptr)]

unsafe {
    let mut b = Box::new(0);
    let ptr1 = Box::as_mut_ptr(&mut b);
    ptr1.write(1);
    let ptr2 = Box::as_mut_ptr(&mut b);
    ptr2.write(2);
    // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
    ptr1.write(3);
}

```

--------------------------------

### Arc::as_ptr example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates obtaining a raw pointer to the data within an Arc without consuming the Arc.

```Rust
use std::sync::Arc;

let x = Arc::new("hello".to_owned());
let y = Arc::clone(&x);
let x_ptr = Arc::as_ptr(&x);
assert_eq!(x_ptr, Arc::as_ptr(&y));
assert_eq!(unsafe { &*x_ptr }, "hello");

```

--------------------------------

### A more practical example demonstrating the need for `Arc::into_inner`.

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

This example illustrates a practical use case for `Arc::into_inner` in preventing stack overflows when dropping deeply nested structures like a linked list, by performing the drop operation in a loop.

```rust
use std::sync::Arc;

// Definition of a simple singly linked list using `Arc`:
#[derive(Clone)]
struct LinkedList<T>(Option<Arc<Node<T>>>);
struct Node<T>(T, Option<Arc<Node<T>>>);

// Dropping a long `LinkedList<T>` relying on the destructor of `Arc`
// can cause a stack overflow. To prevent this, we can provide a
// manual `Drop` implementation that does the destruction in a loop:
impl<T> Drop for LinkedList<T> {
    fn drop(&mut self) {
        let mut link = self.0.take();
        while let Some(arc_node) = link.take() {
            if let Some(Node(_value, next)) = Arc::into_inner(arc_node) {
                link = next;
            }
        }
    }
}

// Implementation of `new` and `push` omitted
impl<T> LinkedList<T> {
    /* ... */
}

// The following code could have still caused a stack overflow
// despite the manual `Drop` impl if that `Drop` impl had used
// `Arc::try_unwrap(arc).ok()` instead of `Arc::into_inner(arc)`.

// Create a long list and clone it
let mut x = LinkedList::new();
let size = 100000;
for i in 0..size {
    x.push(i); // Adds i to the front of x
}
let y = x.clone();

// Drop the clones in parallel
let x_thread = std::thread::spawn(|| drop(x));
let y_thread = std::thread::spawn(|| drop(y));
x_thread.join().unwrap();
y_thread.join().unwrap();
```

--------------------------------

### clone_from_ref_in Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Allocates memory in the given allocator then clones src into it.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

use std::alloc::System;

let hello: Box<str, System> = Box::clone_from_ref_in("hello", System)
```

--------------------------------

### Arc::try_new

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of constructing a new Arc, returning an error if allocation fails.

```rust
#![feature(allocator_api)]
use std::sync::Arc;

let five = Arc::try_new(5)?;

```

--------------------------------

### Arc::try_new_uninit

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of constructing a new Arc with uninitialized contents, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

use std::sync::Arc;

let mut five = Arc::<u32>::try_new_uninit()?;

// Deferred initialization:
Arc::get_mut(&mut five).unwrap().write(5);

let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);

```

--------------------------------

### try_clone_from_ref_in Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Allocates memory in the given allocator then clones src into it, returning an error if allocation fails.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

use std::alloc::System;

let hello: Box<str, System> = Box::try_clone_from_ref_in("hello", System)?
```

--------------------------------

### Arc::clone_from_ref_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates constructing a new Arc with a clone of a value in a specified allocator.

```Rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;

let hello: Arc<str, System> = Arc::clone_from_ref_in("hello", System);

```

--------------------------------

### Trying to create a Box with a value

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example using the experimental Box::try_new function to allocate memory and place a value, handling potential allocation errors.

```Rust
#![feature(allocator_api)]

let five = Box::try_new(5)?;
```

--------------------------------

### take Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Consumes the Box without consuming its allocation, returning the wrapped value and a Box to the uninitialized memory where the wrapped value used to live.

```rust
#![feature(box_take)]

let c = Box::new(5);

// take the value out of the box
let (value, uninit) = Box::take(c);
assert_eq!(value, 5);

// reuse the box for a second value
let c = Box::write(uninit, 6);
assert_eq!(*c, 6)
```

--------------------------------

### Trying to create a Box with zeroed contents

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example using the experimental Box::try_new_zeroed function to construct a Box with zeroed contents, handling potential allocation errors.

```Rust
#![feature(allocator_api)]

let zero = Box::<u32>::try_new_zeroed()?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
```

--------------------------------

### Box::from_raw Example 1

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Recreates a Box from a raw pointer obtained via Box::into_raw.

```Rust
let x = Box::new(5);
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };

```

--------------------------------

### try_new_zeroed_in Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Constructs a new Box with uninitialized contents, with the memory being filled with 0 bytes in the provided allocator, returning an error if allocation fails.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let zero = Box::<u32, _>::try_new_zeroed_in(System)?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### try_new_zeroed_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Illustrates creating an `Arc` with uninitialized contents, where the memory is zero-filled, in a specified allocator, with error handling for allocation failures.

```rust
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let zero = Arc::<u32, _>::try_new_zeroed_in(System)?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
```

--------------------------------

### Creating a Box with uninitialized contents

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example of constructing a Box with uninitialized contents, followed by deferred initialization and assumption of initialization.

```Rust
let mut five = Box::<u32>::new_uninit();
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

--------------------------------

### leak example (simple usage)

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Demonstrates leaking a Box containing a simple type and obtaining a static mutable reference.

```Rust
let x = Box::new(41);
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);
```

--------------------------------

### Box::into_raw Example 2

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Consumes a Box and manually cleans up memory after obtaining a raw pointer.

```Rust
use std::alloc::{dealloc, Layout};
use std::ptr;

let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
unsafe {
    ptr::drop_in_place(ptr);
    dealloc(ptr as *mut u8, Layout::new::<String>());
}

```

--------------------------------

### Arc::try_map example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates attempting to map a value inside an Arc, reusing the allocation if possible, and handling potential allocation failures.

```Rust
#![feature(smart_pointer_try_map)]

use std::sync::Arc;

let b = Arc::new(7);
let new = Arc::try_map(b, |&i| u32::try_from(i)).unwrap();
assert_eq!(*new, 7);

```

--------------------------------

### new_zeroed_in Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Constructs a new Box with uninitialized contents, with the memory being filled with 0 bytes in the provided allocator.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let zero = Box::<u32, _>::new_zeroed_in(System);
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### try_unwrap example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates the usage of `Arc::try_unwrap` to retrieve the inner value if the `Arc` has only one strong reference.

```rust
use std::sync::Arc;

let x = Arc::new(3);
assert_eq!(Arc::try_unwrap(x), Ok(3));

let x = Arc::new(4);
let _y = Arc::clone(&x);
assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4);
```

--------------------------------

### Box::into_raw Example 1

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Consumes a Box and returns a raw pointer, with automatic cleanup via Box::from_raw.

```Rust
let x = Box::new(String::from("Hello"));
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };

```

--------------------------------

### Creating a Weak pointer from an Arc

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

A simple example illustrating how to create a `Weak` pointer from an existing `Arc` using the `Arc::downgrade` method.

```rust
use std::sync::Arc;

let five = Arc::new(5);

let weak_five = Arc::downgrade(&five);

```

--------------------------------

### Arc::try_clone_from_ref_in example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates constructing a new Arc with a clone of a value in a specified allocator, returning an error if allocation fails.

```Rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::sync::Arc;
use std::alloc::System;

let hello: Arc<str, System> = Arc::try_clone_from_ref_in("hello", System)?;

```

--------------------------------

### Creating a Box with zeroed contents

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example of constructing a Box with uninitialized contents, where the memory is filled with 0 bytes, followed by assumption of initialization.

```Rust
let zero = Box::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

--------------------------------

### Converting the raw pointer back into a Box with Box::from_raw_in for automatic cleanup

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example demonstrating how to convert a raw pointer obtained from Box::into_raw_with_allocator back into a Box using Box::from_raw_in to ensure automatic memory cleanup.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let x = Box::new_in(String::from("Hello"), System);
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };

```

--------------------------------

### increment_strong_count Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of incrementing the strong reference count of an Arc from a raw pointer.

```Rust
use std::sync::Arc;

let five = Arc::new(5);

unsafe {
    let ptr = Arc::into_raw(five);
    Arc::increment_strong_count(ptr);

    // This assertion is deterministic because we haven't shared
    // the `Arc` between threads.
    let five = Arc::from_raw(ptr);
    assert_eq!(2, Arc::strong_count(&five));
}

```

--------------------------------

### Minimal example demonstrating the guarantee that `Arc::into_inner` gives.

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

This example shows how `Arc::into_inner` guarantees that exactly one of the calls will return the inner value when called on clones of an Arc in separate threads.

```rust
use std::sync::Arc;

let x = Arc::new(3);
let y = Arc::clone(&x);

// Two threads calling `Arc::into_inner` on both clones of an `Arc`:
let x_thread = std::thread::spawn(|| Arc::into_inner(x));
let y_thread = std::thread::spawn(|| Arc::into_inner(y));

let x_inner_value = x_thread.join().unwrap();
let y_inner_value = y_thread.join().unwrap();

// One of the threads is guaranteed to receive the inner value:
assert!(matches!(
    (x_inner_value, y_inner_value),
    (None, Some(3)) | (Some(3), None)
));
// The result could also be `(None, None)` if the threads called
// `Arc::try_unwrap(x).ok()` and `Arc::try_unwrap(y).ok()` instead.
```

--------------------------------

### Clone implementation for Box<T, A>

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example of cloning a Box<T, A>.

```rust
let x = Box::new(5);
let y = x.clone();

// The value is the same
assert_eq!(x, y);

// But they are unique objects
assert_ne!(&*x as *const i32, &*y as *const i32);
```

--------------------------------

### into_inner Example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Consumes the Box, returning the wrapped value.

```rust
#![feature(box_into_inner)]

let c = Box::new(5);

assert_eq!(Box::into_inner(c), 5)
```

--------------------------------

### type_id function

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/struct.SubrequestSpawner.html

Gets the `TypeId` of `self`. Read more

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Comparison for two `Arc`s.

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates comparing two `Arc` instances using the `cmp` method.

```rust
use std::sync::Arc;
use std::cmp::Ordering;

let five = Arc::new(5);

assert_eq!(Ordering::Less, five.cmp(&Arc::new(6)));

```

--------------------------------

### clone_from implementation for Box<T, A>

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Example of using clone_from to copy contents without reallocation.

```rust
let x = Box::new(5);
let mut y = Box::new(10);
let yp: *const i32 = &*y;

y.clone_from(&x);

// The value is the same
assert_eq!(x, y);

// And no allocation occurred
assert_eq!(yp, &*y);
```

--------------------------------

### by_ref

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Creates a “by reference” adapter for this instance of `Allocator`. This is a nightly-only experimental API.

```rust
fn by_ref(&self) -> &Self
where Self: Sized,
```

--------------------------------

### Arc::new_cyclic

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of constructing a new Arc while providing a Weak pointer to the allocation.

```rust
use std::sync::{Arc, Weak};

struct Gadget {
    me: Weak<Gadget>,
}

impl Gadget {
    /// Constructs a reference counted Gadget.
    fn new() -> Arc<Self> {
        // `me` is a `Weak<Gadget>` pointing at the new allocation of the
        // `Arc` we're constructing.
        Arc::new_cyclic(|me| {
            // Create the actual struct here.
            Gadget { me: me.clone() }
        })
    }

    /// Returns a reference counted pointer to Self.
    fn me(&self) -> Arc<Self> {
        self.me.upgrade().unwrap()
    }
}

```

--------------------------------

### Partial comparison for two `Arc`s.

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates partial comparison between two `Arc` instances using the `partial_cmp` method.

```rust
use std::sync::Arc;
use std::cmp::Ordering;

let five = Arc::new(5);

assert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6)));

```

--------------------------------

### make_mut

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates the clone-on-write behavior of `make_mut` when there are other `Arc` pointers.

```rust
use std::sync::Arc;

let mut data = Arc::new(5);

*Arc::make_mut(&mut data) += 1;         // Won't clone anything
let mut other_data = Arc::clone(&data); // Won't clone inner data
*Arc::make_mut(&mut data) += 1;         // Clones inner data
*Arc::make_mut(&mut data) += 1;         // Won't clone anything
*Arc::make_mut(&mut other_data) *= 2;   // Won't clone anything

// Now `data` and `other_data` point to different allocations.
assert_eq!(*data, 8);
assert_eq!(*other_data, 12);

```

--------------------------------

### Box::from_non_null Example 1

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Recreates a Box from a NonNull pointer obtained via Box::into_non_null.

```Rust
#![feature(box_vec_non_null)]

let x = Box::new(5);
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };

```

--------------------------------

### unwrap_or_clone

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Compares `unwrap_or_clone` with cloning when there is only one reference versus multiple references.

```rust
let inner = String::from("test");
let ptr = inner.as_ptr();

let arc = Arc::new(inner);
let inner = Arc::unwrap_or_clone(arc);
// The inner value was not cloned
assert!(ptr::eq(ptr, inner.as_ptr()));

let arc = Arc::new(inner);
let arc2 = arc.clone();
let inner = Arc::unwrap_or_clone(arc);
// Because there were 2 references, we had to clone the inner value.
assert!(!ptr::eq(ptr, inner.as_ptr()));
// `arc2` is the last reference, so when we unwrap it we get back
// the original `String`.
let inner = Arc::unwrap_or_clone(arc2);
assert!(ptr::eq(ptr, inner.as_ptr()));

```

--------------------------------

### Box::from_raw_in (manual creation)

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Constructs a box from a raw pointer in the given allocator. Manually creates a `Box` from scratch by using the system allocator.

```rust
#![feature(allocator_api, slice_ptr_get)]

use std::alloc::{Allocator, Layout, System};

unsafe {
    let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw_in(ptr, System);
}
```

--------------------------------

### Arc::is_unique example

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates how Arc::is_unique checks for the presence of other Arc or Weak pointers.

```rust
#![feature(arc_is_unique)]

use std::sync::Arc;

let x = Arc::new(3);
assert!(Arc::is_unique(&x));

let y = Arc::clone(&x);
assert!(!Arc::is_unique(&x));
drop(y);

// Weak references also count, because they could be upgraded at any time.
let z = Arc::downgrade(&x);
assert!(!Arc::is_unique(&x));
```

--------------------------------

### Box::clone_from_ref

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Allocates memory on the heap then clones `src` into it. This doesn’t actually allocate if `src` is zero-sized.

```rust
#![feature(clone_from_ref)]

let hello: Box<str> = Box::clone_from_ref("hello");
```

--------------------------------

### Manual cleanup using Box::from_non_null and drop

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Shows an alternative manual cleanup method by converting the NonNull pointer back to a Box and then dropping the Box.

```Rust
#![feature(box_vec_non_null)]

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    drop(Box::from_non_null(non_null));
}
```

--------------------------------

### Box::try_clone_from_ref

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/subrequest/type.UserCtx.html

Allocates memory on the heap then clones `src` into it, returning an error if allocation fails. This doesn’t actually allocate if `src` is zero-sized.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]

let hello: Box<str> = Box::try_clone_from_ref("hello")?;
```

--------------------------------

### from

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Move a boxed object to a new, reference-counted allocation.

```rust
let unique: Box<str> = Box::from("eggplant");
let shared: Arc<str> = Arc::from(unique);
assert_eq!("eggplant", &shared[..]);
```

--------------------------------

### Re-exports

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/prelude/index.html

This section shows the re-exports from the prelude module.

```rust
pub use crate::http_proxy;

```

```rust
pub use crate::http_proxy_service;

```

```rust
pub use crate::ProxyHttp;

```

```rust
pub use crate::Session;

```

--------------------------------

### Arc::new_zeroed

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Example of creating a new Arc with uninitialized contents, memory filled with 0 bytes.

```rust
use std::sync::Arc;

let zero = Arc::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)

```

--------------------------------

### Less-than comparison for two `Arc`s.

Source: https://docs.rs/pingora-proxy/0.8.0/pingora_proxy/type.ProcessCustomSession.html

Demonstrates less-than comparison between two `Arc` instances using the `lt` method.

```rust
use std::sync::Arc;

let five = Arc::new(5);

assert!(five < Arc::new(6));

```
Tokens:
Raw