> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Allocator

> Use the allocator feature to emulate heap memory in a smart contract.

The [allocator example] demonstrates how to utilize the allocator feature when writing a contract.

[![Open in Codespaces](https://github.com/codespaces/badge.svg)][open-in-github-codespaces]

[![Open in Codeanywhere](https://codeanywhere.com/img/open-in-codeanywhere-btn.svg)][open-in-code-anywhere]

[open-in-github-codespaces]: https://github.com/codespaces/new?repo=stellar/soroban-examples&editor=web

[open-in-code-anywhere]: https://app.codeanywhere.com/#https://github.com/stellar/soroban-examples

[allocator example]: https://github.com/stellar/soroban-examples/tree/v23.0.0/alloc

The `soroban-sdk` crate provides a lightweight bump-pointer allocator which can be used to emulate heap memory allocation in a Wasm smart contract.

## Run the Example

First go through the [Setup] process to get your development environment configured, then clone the `v23.0.0` tag of `soroban-examples` repository:

[setup]: https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup.md

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone -b v23.0.0 https://github.com/stellar/soroban-examples
```

Or, skip the development environment setup and open this example in [GitHub Codespaces][open-in-github-codespaces] or [Code Anywhere][open-in-code-anywhere].

To run the tests for the example, navigate to the `alloc` directory, and use `cargo test`.

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
cd alloc
cargo test
```

You should see the output:

```
running 1 test
test test::test ... ok
```

## Dependencies

This example depends on the `alloc` feature in `soroban-sdk`. To include it, add "alloc" to the "features" list of `soroban-sdk` in the `Cargo.toml` file:

```rust title="alloc/Cargo.toml" theme={"theme":{"light":"github-light","dark":"github-dark"}}
[dependencies]
soroban-sdk = { version = "23.0.1", features = ["alloc"] }

[dev_dependencies]
soroban-sdk = { version = "23.0.1", features = ["testutils", "alloc"] }
```

## Code

```rust title="alloc/src/lib.rs" theme={"theme":{"light":"github-light","dark":"github-dark"}}
#![no_std]
use soroban_sdk::{contract, contractimpl, Env};

extern crate alloc;

#[contract]
pub struct AllocContract;

#[contractimpl]
impl AllocContract {
    /// Allocates a temporary vector holding values (0..count), then computes and returns their sum.
    pub fn sum(_env: Env, count: u32) -> u32 {
        let mut v1 = alloc::vec![];
        (0..count).for_each(|i| v1.push(i));

        let mut sum = 0;
        for i in v1 {
            sum += i;
        }

        sum
    }
}
```

Ref: [https://github.com/stellar/soroban-examples/tree/v23.0.0/alloc](https://github.com/stellar/soroban-examples/tree/v23.0.0/alloc)

## How it Works

```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
extern crate alloc;
```

Imports the `alloc` crate, which is required in order to support allocation under `no_std`. See [Contract Rust dialect] for more info about `no_std`.

[contract rust dialect]: https://developers.stellar.org/docs/learn/fundamentals/contract-development/rust-dialect.md

```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
let mut v1 = alloc::vec![];
```

Creates a contiguous growable array `v1` with contents allocated on the heap memory.

> [!NOTE]
>
> The heap memory in the context of a smart contract actually refers to the Wasm linear memory. The `alloc` will use the global allocator provided by the soroban sdk to interact with the linear memory.

> [!WARNING]
>
> Using heap allocated array is typically slow and computationally expensive. Try to avoid it and instead use a fixed-sized array or `soroban_sdk::vec!` whenever possible.
>
> This is especially the case for a large-size array. Whenever the array size grows beyond the current linear memory size, which is multiple of the page size (64KB), the [`wasm32::memory_grow`](https://doc.rust-lang.org/core/arch/wasm32/fn.memory_grow.html) is invoked to grow the linear memory by more pages as necessary, which is very computationally expensive.

The remaining code pushes values `(0..count)` to `v1`, then computes and returns their sum. This is the simplest example to illustrate how to use the allocator.