isc::util::MemorySegment Class Reference

Memory Segment Class. More...

#include <memory_segment.h>

Inheritance diagram for isc::util::MemorySegment:

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 */ }
}

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