Kea: isc::util::MemorySegment Class Reference

| Kea 3.2.0-git

isc::util::MemorySegment Class Referenceabstract

Memory Segment Class. More...

`#include <memory_segment.h>`

Inheritance diagram for isc::util::MemorySegment:
[legend]

## Public Types
typedef std::pair< bool, void * > | NamedAddressResult
| Type definition for result returned by getNamedAddress().

## Public Member Functions
virtual | ~MemorySegment ()
| Destructor.
virtual bool | allMemoryDeallocated () const =0
| Check if all allocated memory was deallocated.
virtual void * | allocate (size_t size)=0
| Allocate/acquire a fragment of memory.
bool | clearNamedAddress (const char *name)
| Delete a name previously associated with a segment address.
virtual void | deallocate (void *ptr, size_t size)=0
| Free/release a segment of memory.
NamedAddressResult | getNamedAddress (const char *name) const
| Return the address in the segment that has the given name.
bool | setNamedAddress (const char *name, void *addr)
| Associate specified address in the segment with a given name.

## Protected Member Functions
virtual bool | clearNamedAddressImpl (const char *name)=0
| Implementation of clearNamedAddress beyond common validation.
virtual NamedAddressResult | getNamedAddressImpl (const char *name) const =0
| Implementation of getNamedAddress beyond common validation.
virtual bool | setNamedAddressImpl (const char *name, void *addr)=0
| Implementation of setNamedAddress beyond common validation.

## Detailed Description

Memory Segment Class.

This class specifies an interface for allocating memory segments. It's intended to provide a unified interface, whether the underlying memory is local to a specific process or is sharable by multiple processes.

This is an abstract class and a real implementation such as MemorySegmentLocal should be used in code.

Definition at line 54 of file memory_segment.h.

## Member Typedef Documentation

## ◆ NamedAddressResult

typedef std::pair<bool, void*> isc::util::MemorySegment::NamedAddressResult

Type definition for result returned by getNamedAddress().

Definition at line 231 of file memory_segment.h.

## Constructor & Destructor Documentation

## ◆ ~MemorySegment()

virtual isc::util::MemorySegment::~MemorySegment | ( |  | ) |
| inlinevirtual

Destructor.

Definition at line 57 of file memory_segment.h.

## Member Function Documentation

## ◆ allMemoryDeallocated()

virtual bool isc::util::MemorySegment::allMemoryDeallocated | ( |  | ) | const
| pure virtual

Check if all allocated memory was deallocated.

Returns
  Returns `true` if all allocated memory (including names associated by memory addresses by `setNamedAddress()`) was deallocated, `false` otherwise.

Implemented in isc::util::MemorySegmentLocal.

## ◆ allocate()

virtual void * isc::util::MemorySegment::allocate | ( | size_t | size | ) |
| pure virtual

Allocate/acquire a fragment of memory.

The source of the memory is dependent on the implementation used.

Depending on the implementation details, it may have to grow the internal memory segment (again, in an implementation dependent way) to allocate the required size of memory. In that case the implementation must grow the internal segment sufficiently so the next call to allocate() for the same size will succeed, and throw a `MemorySegmentGrown` exception (not really allocating the memory yet).

An application that uses this memory segment abstraction to allocate memory should expect this exception, and should normally catch it at an appropriate layer (which may be immediately after a call to `allocate()` or a bit higher layer). It should interpret the exception as any raw address that belongs to the segment may have been remapped and must be re-fetched via an already established named address using the `getNamedAddress()` method.

The intended use case of `allocate()` with the `MemorySegmentGrown` exception is to build a complex object that would internally require multiple calls to `allocate()`:

ComplicatedStuff* stuff = NULL;
while (!stuff) { // this must eventually succeed or result in bad_alloc
try {
// create() is a factory method that takes a memory segment
// and calls allocate() on it multiple times. create()
// provides an exception guarantee that any intermediately
// allocated memory will be properly deallocate()-ed on
// exception.
stuff = ComplicatedStuff::create(mem_segment);
} catch (const MemorySegmentGrown&) { /* just try again */ }
}
isc::util::MemorySegmentGrown
Exception that is thrown, when allocating space in a MemorySegment results in growing the underlying ...
Definition memory_segment.h:31

This way, `create()` can be written as if each call to `allocate()` always succeeds.

Alternatively, or in addition to this, we could introduce a "no throw" version of this method with a way to tell the caller the reason of any failure (whether it's really out of memory or just due to growing the segment). That would be more convenient if the caller wants to deal with the failures on a per-call basis rather than as a set of calls like in the above example. At the moment, we don't expect to have such use-cases, so we only provide the exception version.

Exceptions

  std::bad_alloc | The implementation cannot allocate the requested storage.
  MemorySegmentGrown | The memory segment doesn't have sufficient space for the requested size and has grown internally.
  MemorySegmentError | An attempt was made to allocate storage on a read-only memory segment.

Parameters

  size | The size of the memory requested in bytes.

Returns
  Returns pointer to the memory allocated.

Implemented in isc::util::MemorySegmentLocal.

## ◆ clearNamedAddress()

bool isc::util::MemorySegment::clearNamedAddress | ( | const char * | name | ) |
| inline

Delete a name previously associated with a segment address.

This method deletes the association of the given `name` to a corresponding segment address previously established by `setNamedAddress()`. If there is no association for the given name this method returns false; otherwise it returns true.

Some names are reserved for internal use by this class. If such a name is passed to this method, an `isc::InvalidParameter` exception will be thrown. See `validateName()` method for details.

See `getNamedAddress()` about exception consideration.

Exceptions

  InvalidParameter | name is NULL, empty ("") or begins with an underscore ('_').
  MemorySegmentError | Failure of implementation specific validation.

Parameters

  name | A C string of which the segment memory address is to be deleted. Must not be NULL.

Definition at line 286 of file memory_segment.h.

References clearNamedAddressImpl().

Here is the call graph for this function:

## ◆ clearNamedAddressImpl()

virtual bool isc::util::MemorySegment::clearNamedAddressImpl | ( | const char * | name | ) |
| protectedpure virtual

Implementation of clearNamedAddress beyond common validation.

Implemented in isc::util::MemorySegmentLocal.

Referenced by clearNamedAddress().

## ◆ deallocate()

virtual void isc::util::MemorySegment::deallocate | ( | void * | ptr,
|  | size_t | size )
| pure virtual

Free/release a segment of memory.

This method may throw `isc::OutOfRange` if `size` is not equal to the originally allocated size. `size` could be used by some implementations such as a slice allocator, where freeing memory also requires the size to be specified. We also use this argument in some implementations to test if all allocated memory was deallocated properly.

Specific implementation may also throw `MemorySegmentError` if it encounters violation of implementation specific restrictions.

In general, however, this method must succeed and exception free as long as the caller passes valid parameters (`ptr` specifies memory previously allocated and `size` is correct).

Exceptions

  OutOfRange | The passed size doesn't match the allocated memory size (when identifiable for the implementation).
  MemorySegmentError | Failure of implementation specific validation.

Parameters

  ptr | Pointer to the block of memory to free/release. This should be equal to a value returned by `allocate()`.
  size | The size of the memory to be freed in bytes. This should be equal to the number of bytes originally allocated.

Implemented in isc::util::MemorySegmentLocal.

## ◆ getNamedAddress()

NamedAddressResult isc::util::MemorySegment::getNamedAddress | ( | const char * | name | ) | const
| inline

Return the address in the segment that has the given name.

This method returns the memory address in the segment corresponding to the specified `name`. The name and address must have been associated by a prior call to `setNameAddress()`. If no address associated with the given name is found, it returns NULL.

Some names are reserved for internal use by this class. If such a name is passed to this method, an `isc::InvalidParameter` exception will be thrown. See `validateName()` method for details.

This method should generally be considered exception free, but there can be a small chance it throws, depending on the internal implementation (e.g., if it converts the name to std::string), so the API doesn't guarantee that property. In general, if this method throws it should be considered a fatal condition.

Exceptions

  InvalidParameter | name is NULL, empty ("") or begins with an underscore ('_').

Parameters

  name | A C string of which the segment memory address is to be returned. Must not be NULL.

Returns
  An std::pair containing a bool (set to true if the name was found, or false otherwise) and the address associated with the name (which is undefined if the name was not found).

Definition at line 258 of file memory_segment.h.

References getNamedAddressImpl().

Here is the call graph for this function:

## ◆ getNamedAddressImpl()

virtual NamedAddressResult isc::util::MemorySegment::getNamedAddressImpl | ( | const char * | name | ) | const
| protectedpure virtual

Implementation of getNamedAddress beyond common validation.

Implemented in isc::util::MemorySegmentLocal.

Referenced by getNamedAddress().

## ◆ setNamedAddress()

bool isc::util::MemorySegment::setNamedAddress | ( | const char * | name,
|  | void * | addr )
| inline

Associate specified address in the segment with a given name.

This method establishes an association between the given name and the address in an implementation specific way. The stored address is retrieved by the name later by calling `getNamedAddress()`. If the underlying memory segment is sharable by multiple processes, the implementation must ensure the portability of the association; if a process gives an address in the shared segment a name, another process that shares the same segment should be able to retrieve the corresponding address by that name (in such cases the real address may be different between these two processes).

Some names are reserved for internal use by this class. If such a name is passed to this method, an `isc::InvalidParameter` exception will be thrown. See `validateName()` method for details.

`addr` must be 0 (NULL) or an address that belongs to this segment. The latter case means it must be the return value of a previous call to `allocate()`. The actual implementation is encouraged to detect violation of this restriction and signal it with an exception, but it's not an API requirement. It's generally the caller's responsibility to meet the restriction. Note that NULL is allowed as `addr` even if it wouldn't be considered to "belong to" the segment in its normal sense; it can be used to indicate that memory has not been allocated for the specified name. A subsequent call to `getNamedAddress()` will return NamedAddressResult(true, NULL) for that name.

Note
  Naming an address is intentionally separated from allocation so that, for example, one module of a program can name a memory region allocated by another module of the program.

There can be an existing association for the name; in that case the association will be overridden with the newly given address.

While normally unexpected, it's possible that available space in the segment is not sufficient to allocate a space (if not already exist) for the specified name in the segment. In that case, if possible, the implementation should try to grow the internal segment and retry establishing the association. The implementation should throw std::bad_alloc if even reasonable attempts of retry still fail.

This method should normally return false, but if the internal segment had to grow to store the given name, it must return true. The application should interpret it just like the case of `MemorySegmentGrown` exception thrown from the `allocate()` method.

Note
  The behavior in case the internal segment grows is different from that of `allocate()`. This is intentional. In intended use cases (for the moment) this method will be called independently, rather than as part of a set of allocations. It's also expected that other raw memory addresses (which would have been invalidated due to the change to the segment) won't be referenced directly immediately after this call. So, the caller should normally be able to call this method as mostly never-fail one (except in case of real memory exhaustion) and ignore the return value.

Exceptions

  std::bad_alloc | Allocation of a segment space for the given name failed.
  InvalidParameter | name is NULL, empty ("") or begins with an underscore ('_').
  MemorySegmentError | Failure of implementation specific validation.

Parameters

  name | A C string to be associated with `addr`. Must not be NULL.
  addr | A memory address returned by a prior call to `allocate`.

Returns
  true if the internal segment has grown to allocate space for the name; false otherwise (see above).

Definition at line 222 of file memory_segment.h.

References setNamedAddressImpl().

Here is the call graph for this function:

## ◆ setNamedAddressImpl()

virtual bool isc::util::MemorySegment::setNamedAddressImpl | ( | const char * | name,
|  | void * | addr )
| protectedpure virtual

Implementation of setNamedAddress beyond common validation.

Implemented in isc::util::MemorySegmentLocal.

Referenced by setNamedAddress().

The documentation for this class was generated from the following file:

- memory_segment.h