sassim.h File Reference

Shared Address Space, base runtime for shared and persistent memory for multi-thread/multi-core applications. More...

#include <stdlib.h>

Go to the source code of this file.

Typedefs
typedef unsigned long	sasseg_t
	SAS segment ID. More...

Functions
__C__ unsigned long	getMemLow ()
	Get the Region's lowest memory address. More...
__C__ unsigned long	getMemHigh ()
	Get the Region's highest memory address. More...
__C__ void	setSASmemrange (unsigned long low, unsigned long high)
	Set the Region's low/high memory address for testing. More...
__C__ int	SASJoinRegion ()
	Join this process to a SAS Region. More...
__C__ int	SASJoinRegionByName (const char *store_name)
	Join this process to a named SAS Region. More...
__C__ void *	SASBlockAlloc (unsigned long blockSize)
	Allocate a block of memory within SAS Storage. More...
__C__ void	SASBlockDealloc (void *blockAddr, unsigned long blockSize)
	Deallocate a block of memory within SAS Storage. More...
__C__ void	SASListFreeRegion (void **blockAddr, unsigned long *blockSize, int *count)
	Return lists of currently free segment block addresses and sizes. More...
__C__ void	SASListAllocatedRegion (void **blockAddr, unsigned long *blockSize, int *count)
	Return lists of currently allocated segment block addresses and sizes. More...
__C__ void	SASListInUseMem (void **blockAddr, unsigned long *blockSize, int *count)
	Return lists of currently allocated block addresses and sizes. More...
__C__ void	SASListFreeMem (void **blockAddr, unsigned long *blockSize, int *count)
	Return lists of freed block addresses and sizes. More...
__C__ void	SASListUncommittedMem (void **blockAddr, unsigned long *blockSize, int *count)
	Return lists of currently uncommitted block addresses and sizes. More...
__C__ unsigned int	SASAnchorFreeSpace ()
	Get the current number of free bytes within the Anchor blocks internal heap. More...
__C__ void	SASReset ()
	Reset the SAS Region back to initial state. More...
__C__ void	SASSeize ()
	Seize the anchor block master lock. More...
__C__ void	SASRelease ()
	Release the anchor block master lock. More...
__C__ void	SASResetSem ()
	Reset the internal Semaphores used by Seize/Release the SAS lock manager. More...
__C__ void	SASCleanUp ()
	Process wide cleanup for the SAS runtime. +* +*. More...
__C__ void	SASThreadSetUp ()
	Thread specific setup for secondary thread accessing the SAS region. More...
__C__ void	SASThreadCleanUp ()
	Thread specific cleanup for secondary thread accessing the SAS region. More...
__C__ void	SASRemove ()
	Remove the SAS Region. More...
__C__ void	setSASFinder (void *)
	Sets the SAS finder pointer to a SAS block or utility object. More...
__C__ void *	getSASFinder ()
	Get the SAS finder address. More...

Variables
__C__ int	sasClearOnDealloc
	SAS clear on block deallocate flag. More...

Detailed Description

Shared Address Space, base runtime for shared and persistent memory for multi-thread/multi-core applications.

! Provides APIs to manage (setup and take-down) the SAS Region and backing store for cooperating processes. The region is a contiguous subrange of the process address space. The exact range varies based on the platform on the platform (as defined in sasconf.h).

Associated with an active SAS region is SAS Store which is a directory contain backing files which are memory mapped for the active portions of the region. A region is fully qualified by its SAS Store (directory) path. Processes joined to the same SAS story are accessing the same data at the same virtual address.

Note

: For Linux this means memory mapping the pages from the kernel's file cache, and so we are sharing the same real pages across all partipating processes. This enables zero copy sharing and persistence.

Processes using different SAS Store paths are accessing logically different and disjoint regions. A process can only access one SAS region but there is no limit (other than files system capacity) to the number different SAS regions accessed by different groups of cooperating processes.

The SAS region address range and backing file store are managed via a power of 2 buddy system. Logically the region is divided into segments and blocks. Segment are a fixed power of 2 size (defined for the platform by sasconf.h) and alignment within the region. Blocks are a variable power of 2 size and have an alignment matching their size or better. Logically blocks are sub-allocated from allocated segments (have a backing file and can be mmaped) which are sub-allocated from the region.

Todo:

The current runtime restricts blocks to segment size or smaller. Creating larger blocks would require creating (power of 2) multiple segments (and backing files which have to memory mapped) while holding the global anchor block lock. Future releases may remove this restriction.

Note

Segments and blocks inherit their virtual address (within the process) from the region. The region has a fixed starting address and segments always have a unique offset (and file index) within the region. The segment's file index is used to generate the unique file name within the SAS store directory. Obviously blocks inherit their virtual address from the containing segment which inherits from the region.

The segment is the granule of backing file allocation and memory mapping. Segment backing files are always extended to the full segment size at creation. This minimizes OS overhead by minimizing file system and memory mapping operations at runtime. Segments are not allocated (and backing files created) until additional block space is needed (when free block space, of the required size and alignment, in currently allocated segments, is depleted). This is done implicitly under the block allocate call.

Note

SASJoinRegion and related functions (SASTHreadSetUp) establish a sigaction handler for signal SIGSEGV. This handles the case when one process, sharing a named Region allocates a new segment and backing. Other processes (sharing the same Region) are not immediately aware of this and need not perform any specific actions until or unless that process references data in that segment. This will generate a SIGSEGV and the SAS sigaction handler will attach this segment by mmapping the associated backing file into the faulting process at the assigned address.

Applications that set their own signal to sigaction handlers for SIGSEGV should be aware of this and plan for proper nesting. Applications should establish their SIGSEGV handlers before joining. The SASJoinRegion will preserve the the "old action" as part of setting it own SIGSEGV handler.

When the SPHDE runtime handler gets control it will verify that the faulting address is within the SAS Region. If it is not, it is likely a error or something that the application should handle itself. The SPHDE runtime handler will check if the "old action" was SIG_DFL or has it own signal or sigaction handler. If the application defined it own handler SPHDE will attempt to call that handler. Otherwise SPHDE runtime handler will print a back trace and exit the effected process (or thread).

The runtime also sets up shared memory segments (shmat) for SAS locks. SAS locks need to be shared but should not persist across reboot (like memory mapped files do). Different SAS stores must have independent locks (different lock segments). So lock segments are allocated/attached via shmget/shmat using a key generated (ftok) from the SAS Store path.

Typedef Documentation

typedef unsigned long sasseg_t

SAS segment ID.

Internal typedef that identifies a segment (process address range and backing file name) within the SAS Store (directory).

Function Documentation

__C__ unsigned long getMemHigh

(

)

Get the Region's highest memory address.

With getMemLow() defines the Region (starting process address and extent).

Returns

the address value for the highest extent (+1) of the SAS Region.

__C__ unsigned long getMemLow

(

)

Get the Region's lowest memory address.

With getMemHigh() defines the Region (starting process address and extent).

Returns

the address value for the lowest extent of the SAS Region.

__C__ void* getSASFinder

(

)

Get the SAS finder address.

Returns

the SAS finder address from the anchor block.

__C__ unsigned int SASAnchorFreeSpace

(

)

Get the current number of free bytes within the Anchor blocks internal heap.

Note

Low values can prevent managing large or fragmented regions. In this case consider increasing the anchor block size.

Returns

the number of free bytes remaining in the anchor blocks heap.

__C__ void* SASBlockAlloc

(

unsigned long

blockSize

)

Allocate a block of memory within SAS Storage.

Blocks are allocated within the SAS region. Blocks must be a power of 2 in size (256 bytes >= and <= segmentSize). Allocated blocks always have alignment equal to their size or better.

If the required space is not found within a segment backed by existing files in the SAS store, a new segment backing file is created in the SAS store directory and mmaped into the region and added to region free space. This automatically extends the SAS Store as needed to satisfy block allocate requests.

Parameters

blockSize

size of the block to be allocated.

Returns

the address of the start of the allocated block, or NULL if the allocation fails.

__C__ void SASBlockDealloc	(	void *	blockAddr,
		unsigned long	blockSize
	)

Deallocate a block of memory within SAS Storage.

Blocks within the SAS Region are freed by adding the block range to the free list. Adjacent free blocks of equal size and appropriate alignment are combined into larger free blocks.

Parameters

blockAddr	address of start of the block to be deallocated.
blockSize	size of the block to be deallocated.

__C__ void SASCleanUp

(

)

Process wide cleanup for the SAS runtime. +* +*.

Warning

Do not attempt to use SAS/SPH APIs or access the SAS region after this call. +* +*

Threaded applications should pthread_join their child threads before this call. +* +* Unmap all SAS segments and detach the shmem segments used for locks. +* The runtime disables the sigsegv handler for the main thread. +*

__C__ int SASJoinRegion

(

)

Join this process to a SAS Region.

Join this process to the SAS Region based on the anchor segment in the SAS Store (either the default '.' directory or the path specified in the environment variable SASSTOREPATH). The anchor segment contains the anchor block including the indexes that manage segments and (free and allocated) block space within the region.

If the backing file for the anchor segment does not exist in the SAS Store directory, the runtime creates a "SegmentSize" backing file and mmaps that file at SAS memLow. The lowest part of this segment is initialed as the SAS anchor block.

Otherwise the the runtime mmaps the anchor segment at memLow and proceeds to bring up the rest of the SAS environment. This includes mmaping additional segments from the SAS Store.

The join function also checks for, and if needed initializes, the matching lock segments. The lock segments are allocated/attached via shmget/shmat using a key generated from the SAS Store path. This insures that applications using different SAS stores also have independent lock segments.

@return a 0 value indicates success, otherwise failure.

__C__ int SASJoinRegionByName

(

const char *

store_name

)

Join this process to a named SAS Region.

Join this process to the SAS Region based on the anchor segment backing file in the named SAS Store. The anchor segment contains the anchor block including the indexes that manage segments and (free and allocated) block space within the region.

If the backing file for the anchor segment does not exist in the SAS Store directory, the runtime creates a "SegmentSize" backing file and mmaps that file at SAS memLow. The lowest part of this segment is initialed as the SAS anchor block.

Otherwise the the runtime mmaps the anchor segment at memLow and proceeds to bring up the rest of the SAS environment. This includes mmaping additional segments from the SAS Store.

The join function also checks for, and if needed initializes, the matching lock segments. The lock segments are allocated/attached via shmat using a key generated from the SAS Store path. This insures that applications using different SAS stores also have independent lock segments.

Finally the runtime sets up as sigsegv handler. This allows the SAS runtime to automatically attach segments created by other processes in this SAS store.

Parameters

store_name

C string containing the path to this SAS store directory.

Returns

a 0 value indicates success, otherwise failure.

__C__ void SASListAllocatedRegion	(	void **	blockAddr,
		unsigned long *	blockSize,
		int *	count
	)

Return lists of currently allocated segment block addresses and sizes.

Returns the addresses and sizes of power of 2 sized segment blocks currently allocated within the region. It is possible for the allocated list to cover combined segment blocks of (power of 2) multiple segments. Blocks on the regions allocated list always represent segments with a backing file in the SAS Store directory.

Parameters

blockAddr	address of an array or addresses to be filled in.
blockSize	address of an array of block size values to be filled in.
count	address of a int to be filled in with the actual count of entries.

Todo:

should change this API to pass the max array size as a parm and return the actual count.

__C__ void SASListFreeMem	(	void **	blockAddr,
		unsigned long *	blockSize,
		int *	count
	)

Return lists of freed block addresses and sizes.

Returns the addresses and sizes of power of 2 sized blocks currently freed within the region. Blocks on the freed list are a sub range of existing segments with a backing file in the SAS Store directory. It is possible for the free list to cover combined blocks of multiple (power of 2) segments.

Parameters

blockAddr	address of an array or addresses to be filled in.
blockSize	address of an array of block size values to be filled in.
count	address of a int to be filled in with the actual count of entries.

Todo:

should change this API to pass the max array size as a parm and return the actual count.

__C__ void SASListFreeRegion	(	void **	blockAddr,
		unsigned long *	blockSize,
		int *	count
	)

Return lists of currently free segment block addresses and sizes.

Returns the addresses and sizes of power of 2 sized segment blocks in the regions free list. It is possible for the free list to cover combined segment blocks of (power of 2) multiple segments. Blocks on the regions free list will not have backing files in the SAS store directory.

Parameters

blockAddr	address of an array or addresses to be filled in.
blockSize	address of an array of block size values to be filled in.
count	address of a int to be filled in with the actual count of entries.

Todo:

should change this API to pass the max array size as a parm and return the actual count.

__C__ void SASListInUseMem	(	void **	blockAddr,
		unsigned long *	blockSize,
		int *	count
	)

Return lists of currently allocated block addresses and sizes.

Returns the addresses and sizes of power of 2 sized blocks currently allocated within the region. Blocks on the allocated list are a sub range of existing segments with a backing file in the SAS Store directory.

Parameters

blockAddr	address of an array or addresses to be filled in.
blockSize	address of an array of block size values to be filled in.
count	address of a int to be filled in with the actual count of entries.

Todo:

should change this API to pass the max array size as a parm and return the actual count.

__C__ void SASListUncommittedMem	(	void **	blockAddr,
		unsigned long *	blockSize,
		int *	count
	)

Return lists of currently uncommitted block addresses and sizes.

Returns the addresses and sizes of power of 2 sized blocks uncommitted blocks within the region. Uncommitted blocks are a sub range of existing segments with a backing file in the SAS Store directory, but have never been allocated. Newly created segments start as uncommitted storage and can be assumed to be initialized to zero.

Parameters

blockAddr	address of an array or addresses to be filled in.
blockSize	address of an array of block size values to be filled in.
count	address of a int to be filled in with the actual count of entries.

Todo:

should change this API to pass the max array size as a parm and return the actual count.

__C__ void SASRelease

(

)

Release the anchor block master lock.

__C__ void SASRemove

(

)

Remove the SAS Region.

Warning

SASRemove will result in the immediate lose of user data within the SAS Region.

Unmap all segments and delete all backing files. Remove the shmem segments used for locks.

__C__ void SASReset

(

)

Reset the SAS Region back to initial state.

Warning

SASReset will result in the immediate lose of user data within the SAS Region.

Unmap any segments and delete backing files beyond the anchor segment. Reinitialize the anchor block and lock segments to initial region state.

__C__ void SASResetSem

(

)

Reset the internal Semaphores used by Seize/Release the SAS lock manager.

Warning

Should not be called when multiple cooperating processes or threads are accessing the SAS region. Should only be used to recover from an application crash.

Reset internal semaphore to their initial state.

__C__ void SASSeize

(

)

Seize the anchor block master lock.

Used to serialize access to the anchor block and internal data structures.

__C__ void SASThreadCleanUp

(

)

Thread specific cleanup for secondary thread accessing the SAS region.

For secondary threads that called SASThreadSetUp(), SASThreadCleanUp() should be called before thread exit. The runtime disables the sigsegv handler for this thread.

__C__ void SASThreadSetUp

(

)

Thread specific setup for secondary thread accessing the SAS region.

Warning

Each secondary thread of a SAS/SPH application should call this function before accessing data within the SAS Region.

The runtime sets up a sigsegv handler for this thread. This allows the SAS runtime to automatically attach SAS segments created by other processes.

__C__ void setSASFinder

(

void *

)

Sets the SAS finder pointer to a SAS block or utility object.

Warning

The finder address is a shared SAS resource and must point to a block or utility object within the SAS region.

Stores the region wide finder address within the anchor block.

Note

the finder is normally a SPHContext containing name / address associations for application data and other utility objects with the SAS region. This helps the application find it's data and data created by cooperating applications during startup. While setting the finder to a context is normal it can be any data structure or other utility object useful to the application.

__C__ void setSASmemrange	(	unsigned long	low,
		unsigned long	high
	)

Set the Region's low/high memory address for testing.

Parameters

low	defines the regions starting address.
high	defines the regions ending address.

Variable Documentation

__C__ int sasClearOnDealloc

SAS clear on block deallocate flag.

Internal flag that requests the SAS runtime to clear blocks as they are deallocated.