Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Donate
- Resources
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# std.experimental.allocator.building_blocks.region

struct `Region`(ParentAllocator = NullAllocator, uint minAlign = platformAlignment, Flag!"growDownwards" growDownwards = No.growDownwards);
  A `Region` allocator allocates memory straight from one contiguous chunk. There is no deallocation, and once the region is full, allocation requests return `null`. Therefore, `Region`s are often used (a) in conjunction with more sophisticated allocators; or (b) for batch-style very fast allocations that deallocate everything at once.
  The region only stores three pointers, corresponding to the current position in the store and the limits. One allocation entails rounding up the allocation size for alignment purposes, bumping the current pointer, and comparing it against the limit.
  If ParentAllocator is different from NullAllocator, `Region` deallocates the chunk of memory during destruction.
  The minAlign parameter establishes alignment. If minAlign > 1, the sizes of all allocation requests are rounded up to a multiple of minAlign. Applications aiming at maximum speed may want to choose minAlign = 1 and control alignment externally.
  Examples:

      import std.algorithm.comparison : max;
      import std.experimental.allocator.building_blocks.allocator_list
          : AllocatorList;
      import std.experimental.allocator.mallocator : Mallocator;
      import std.typecons : Ternary;
      // Create a scalable list of regions. Each gets at least 1MB at a time by
      // using malloc.
      auto batchAllocator = AllocatorList!(
          (size_t n) => Region!Mallocator(max(n, 1024 * 1024))
      )();
      writeln(batchAllocator.empty); // Ternary.yes
      auto b = batchAllocator.allocate(101);
      writeln(b.length); // 101
      writeln(batchAllocator.empty); // Ternary.no
      // This will cause a second allocation
      b = batchAllocator.allocate(2 * 1024 * 1024);
      writeln(b.length); // 2 * 1024 * 1024
      // Destructor will free the memory

  ParentAllocator `parent`;
    The parent allocator. Depending on whether ParentAllocator holds state or not, this is a member variable or an alias for ParentAllocator.instance.
  this(ubyte[] `store`);
  this(size_t `n`);
    Constructs a region backed by a user-provided `store`. Assumes `store` is aligned at minAlign. Also assumes the memory was allocated with ParentAllocator (if different from NullAllocator).
    Parameters:

    ubyte[] `store` | User-provided `store` backing up the region. `store` must be aligned at minAlign (enforced with assert). If ParentAllocator is different from NullAllocator, memory is assumed to have been allocated with ParentAllocator.
    size_t `n` | Bytes to allocate using ParentAllocator. This constructor is only defined If ParentAllocator is different from NullAllocator. If parent.allocate(`n`) returns `null`, the region will be initialized as empty (correctly initialized but unable to allocate).

  alias `alignment` = minAlign;
    Alignment offered.
  void[] `allocate`(size_t `n`);
    Allocates `n` bytes of memory. The shortest path involves an alignment adjustment (if alignment > 1), an increment, and a comparison.
    Parameters:

    size_t `n` | number of bytes to `allocate`

    Returns:
    A properly-aligned buffer of size `n` or `null` if request could not be satisfied.
  void[] `alignedAllocate`(size_t `n`, uint `a`);
    Allocates `n` bytes of memory aligned at alignment `a`.
    Parameters:

    size_t `n` | number of bytes to allocate
    uint `a` | alignment for the allocated block

    Returns:
    Either `a` suitable block of `n` bytes aligned at `a`, or `null`.
  void[] `allocateAll`();
    Allocates and returns all memory available to this region.
  pure nothrow @nogc @safe bool `expand`(ref void[] `b`, size_t `delta`);
    Expands an allocated block in place. Expansion will succeed only if the block is the last allocated. Defined only if growDownwards is No.growDownwards.
  pure nothrow @nogc bool `deallocate`(void[] `b`);
    Deallocates `b`. This works only if `b` was obtained as the last call to allocate; otherwise (i.e. another allocation has occurred since) it does nothing. This semantics is tricky and therefore `deallocate` is defined only if Region is instantiated with Yes.defineDeallocate as the third template argument.
    Parameters:

    void[] `b` | Block previously obtained by a call to allocate against this allocator (`null` is allowed).

  pure nothrow @nogc bool `deallocateAll`();
    Deallocates all memory allocated by this region, which can be subsequently reused for new allocations.
  const pure nothrow @nogc @trusted Ternary `owns`(const void[] `b`);
    Queries whether `b` has been allocated with this region.
    Parameters:

    void[] `b` | Arbitrary block of memory (null is allowed; `owns`(null) returns false).

    Returns:
    true if `b` has been allocated with this region, false otherwise.
  const pure nothrow @nogc @safe Ternary `empty`();
    Returns Ternary.yes if no memory has been allocated in this region, Ternary.no otherwise. (Never returns Ternary.unknown.)
  const size_t `available`();
    Nonstandard property that returns bytes `available` for allocation.
struct `InSituRegion`(size_t size, size_t minAlign = platformAlignment);
  `InSituRegion` is a convenient region that carries its storage within itself (in the form of a statically-sized array).
  The first template argument is the size of the region and the second is the needed alignment. Depending on the alignment requested and platform details, the actual available storage may be smaller than the compile-time parameter. To make sure that at least n bytes are available in the region, use `InSituRegion`!(n + a - 1, a).
  Given that the most frequent use of `InSituRegion` is as a stack allocator, it allocates starting at the end on systems where stack grows downwards, such that hot memory is used first.
  Examples:

      // 128KB region, allocated to x86's cache line
      InSituRegion!(128 * 1024, 16) r1;
      auto a1 = r1.allocate(101);
      writeln(a1.length); // 101

      // 128KB region, with fallback to the garbage collector.
      import std.experimental.allocator.building_blocks.fallback_allocator
          : FallbackAllocator;
      import std.experimental.allocator.building_blocks.free_list
          : FreeList;
      import std.experimental.allocator.building_blocks.bitmapped_block
          : BitmappedBlock;
      import std.experimental.allocator.gc_allocator : GCAllocator;
      FallbackAllocator!(InSituRegion!(128 * 1024), GCAllocator) r2;
      const a2 = r2.allocate(102);
      writeln(a2.length); // 102

      // Reap with GC fallback.
      InSituRegion!(128 * 1024, 8) tmp3;
      FallbackAllocator!(BitmappedBlock!(64, 8), GCAllocator) r3;
      r3.primary = BitmappedBlock!(64, 8)(cast(ubyte[])(tmp3.allocateAll()));
      const a3 = r3.allocate(103);
      writeln(a3.length); // 103

      // Reap/GC with a freelist for small objects up to 16 bytes.
      InSituRegion!(128 * 1024, 64) tmp4;
      FreeList!(FallbackAllocator!(BitmappedBlock!(64, 64), GCAllocator), 0, 16) r4;
      r4.parent.primary = BitmappedBlock!(64, 64)(cast(ubyte[])(tmp4.allocateAll()));
      const a4 = r4.allocate(104);
      writeln(a4.length); // 104

  alias `alignment` = minAlign;
    An alias for minAlign, which must be a valid `alignment` (nonzero power of 2). The start of the region and all allocation requests will be rounded up to a multiple of the `alignment`.

        InSituRegion!(4096) a1;
        assert(a1.alignment == platformAlignment);
        InSituRegion!(4096, 64) a2;
        assert(a2.alignment == 64);

  void[] `allocate`(size_t `n`);
    Allocates bytes and returns them, or `null` if the region cannot accommodate the request. For efficiency reasons, if bytes == 0 the function returns an empty non-`null` slice.
  void[] `alignedAllocate`(size_t `n`, uint `a`);
    As above, but the memory allocated is aligned at `a` bytes.
  bool `deallocate`(void[] `b`);
    Deallocates `b`. This works only if `b` was obtained as the last call to allocate; otherwise (i.e. another allocation has occurred since) it does nothing. This semantics is tricky and therefore `deallocate` is defined only if Region is instantiated with Yes.defineDeallocate as the third template argument.
    Parameters:

    void[] `b` | Block previously obtained by a call to allocate against this allocator (`null` is allowed).

  pure nothrow @nogc @safe Ternary `owns`(const void[] `b`);
    Returns Ternary.yes if `b` is the result of a previous allocation, Ternary.no otherwise.
  bool `expand`(ref void[] `b`, size_t `delta`);
    Expands an allocated block in place. Expansion will succeed only if the block is the last allocated.
  bool `deallocateAll`();
    Deallocates all memory allocated with this allocator.
  void[] `allocateAll`();
    Allocates all memory available with this allocator.
  size_t `available`();
    Nonstandard function that returns the bytes `available` for allocation.
struct `SbrkRegion`(uint minAlign = platformAlignment);
  Allocator backed by sbrk for Posix systems. Due to the fact that sbrk is not thread-safe by design, `SbrkRegion` uses a mutex internally. This implies that uncontrolled calls to brk and sbrk may affect the workings of `SbrkRegion` adversely.
  static shared SbrkRegion `instance`;
    Instance shared by all callers.
  enum uint `alignment`;
  shared void[] `allocate`(size_t `bytes`);
  shared void[] `alignedAllocate`(size_t `bytes`, uint `a`);
    Standard allocator primitives.
  shared nothrow @nogc @trusted bool `expand`(ref void[] `b`, size_t `delta`);
  shared pure nothrow @nogc @trusted Ternary `owns`(const void[] `b`);
    The `expand` method may only succeed if the argument is the last block allocated. In that case, `expand` attempts to push the break pointer to the right.
  shared nothrow @nogc bool `deallocate`(void[] `b`);
    The `deallocate` method only works (and returns `true`) on systems that support reducing the break address (i.e. accept calls to sbrk with negative offsets). OSX does not accept such. In addition the argument must be the last block allocated.
  shared nothrow @nogc bool `deallocateAll`();
    The `deallocateAll` method only works (and returns `true`) on systems that support reducing the break address (i.e. accept calls to sbrk with negative offsets). OSX does not accept such.
  shared pure nothrow @nogc @safe Ternary `empty`();
    Standard allocator API.

Copyright © 1999-2018 by the D Language Foundation | Page generated by Ddoc on Tue Jan 2 20:55:10 2018