handles.h File Reference

(r1785/r751)

Go to the source code of this file.

Typedefs
typedef UINT32	MHANDLE
Functions
BOOL	InitHandles ()
	Starts up the Handles stuff. It sets all the handles in the table to sensible starting values and inits a count of the number of handles.
void	DeinitHandles ()
	Closes down the Handles manager. Should free up any space allocated by the Handle Manager during it life.
MHANDLE	ClaimHandle (ADDR Address)
	Allocates a handle to the supplied address. The handle should be used as the reference to the memory location from then on to allow the memory manager to move the allocation around.
BOOL	ReleaseHandle (MHANDLE Handle)
	To free up a handle that is no longer required by its user Notes: There are 2 versions of this function below - one is used if USE_UNIQUE_IDS is defined and the other if it is not.
BOOL	ReleaseRangeOfHandles (ADDR LowAddr, ADDR HighAddr)
	Find all the handles that refer to address in the the given range and release them.
ADDR	DescribeHandle (MHANDLE Handle)
	To get an up to date location of the memory location.
BOOL	RelocateHandles (ADDR LowAddr, ADDR HighAddr, INT32 shift)
	Finds all the memory locations in the supplied region that have handles associated with them and modifies the address. Usually called by the memory manager when it shifts a block of memory to a different location.
ADDR	AlterHandle (MHANDLE Handle, ADDR Address)
	The change the location associated with the handle without having to release and then re-claim a new handle.
Variables
const MHANDLE	BAD_MHANDLE = MHANDLE(NULL)

---

Typedef Documentation

typedef UINT32 MHANDLE

Definition at line 114 of file handles.h.

---

Function Documentation

ADDR AlterHandle (  MHANDLE  Handle, ADDR  Address )

The change the location associated with the handle without having to release and then re-claim a new handle. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 27/04/93 Parameters: Handle  - A handle currently in use by the caller [INPUTS] Address - The new memory location to associate with the handle Size - The new size of the the block Returns: The old address that used to be associated with the handle Definition at line 364 of file handles.cpp. { ADDR OldAddr; #ifdef USE_UNIQUE_IDS // Make sure its not garbage ENSURE( LOWORD(Handle) > BAD_MHANDLE, "AlterHandle: Handle was bad" ); ENSURE( LOWORD(Handle) < ElementsInHandleTable, "AlterHandle: Handle too big" ); // note old value and change it to the new one OldAddr = HandlesTable[LOWORD(Handle)].Address; HandlesTable[ LOWORD(Handle) ].Address = Address; #else // make sure its not garbage ENSURE( Handle > BAD_MHANDLE, "AlterHandle: Handle was bad" ); ENSURE( Handle < ElementsInHandleTable, "AlterHandle: Handle was too big" ); // note old value and change it to the new one OldAddr = HandlesTable[Handle].Address; HandlesTable[Handle].Address = Address; #endif // retrun back the old value return OldAddr; }

MHANDLE ClaimHandle (  ADDR  Address  )

Allocates a handle to the supplied address. The handle should be used as the reference to the memory location from then on to allow the memory manager to move the allocation around. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 27/04/93 Parameters: Address  - The address of a block or somewhere in a block of allocated [INPUTS] memory. Size - The size of the block of memory being stored. If zero then just a pointer stored. If this parameter is not passed, then zero assumed Returns: A handle to the address or BAD_MHANDLE Definition at line 505 of file handles.cpp. { // Need to scan along the list of handles to find an unused one if (HandlesInUse == (ElementsInHandleTable-1)) { // we have run out of handles TRACEUSER( "Rik", wxT("ClaimHandle - No more handles available. Trying to get some more\n") ); // First off we had better try to extend our allocation of memory to the table // If it fails, return saying there are no more handles left! if (!HandlesMemory.Grow(HandleTableTotalSize, HandleTableTotalSize+HandleTableByteSize, (LPVOID*)&HandlesTable )) { TRACE( wxT("ClaimHandle - Failed to get more handles!!!! P A N I C\n") ); return BAD_MHANDLE; } // grew handle table OK, Set all the new bits of mem to defaults for (INT32 i=0; i<HandleTableSize; i++) HandlesTable[ElementsInHandleTable+i].Address = PBYTE(BAD_MHANDLE); // increase the counters HandleTableTotalSize += HandleTableByteSize; ElementsInHandleTable += HandleTableSize; } // Ok, we must have some handles by now, so lets try and find one UINT32 Handle = ElementsInHandleTable - 1; while (Handle>0) { if (HandlesTable[Handle].Address == BAD_MHANDLE ) { // Store the Addr HandlesTable[Handle].Address = Address; HandlesInUse ++; // if we are using unique IDs, do this #ifdef USE_UNIQUE_IDS // Using Unique IDS, so get the next id and store it away WORD UniqueID = CurrUniqueId++; HandlesTable[ Handle ].UniqueID = UniqueID; return MAKEINT32( Handle, UniqueID ); #else // TRACEUSER("Gerry", _T("ClaimHandle - %d"), Handle); return Handle; #endif } Handle --; } // Should never get here ENSURE( FALSE, "ClaimHandle: We Should never have reached this bit!" ); return BAD_MHANDLE; }

void DeinitHandles (   )

Closes down the Handles manager. Should free up any space allocated by the Handle Manager during it life. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 27/04/93 Definition at line 204 of file handles.cpp. { #ifdef _DEBUG // Tell me how many handles were in use at its peak TRACE( wxT("DeinitHandles: Max size of handle table = %ld"), ElementsInHandleTable ); // Tell everyone about any handles that were not released UINT32 Waste = 0; for (UINT32 n=1; n<ElementsInHandleTable; n++) { if (HandlesTable[n].Address != BAD_MHANDLE ) { TRACE( wxT("Handle %d not released (0x%08x)"), n, HandlesTable[n].Address); Waste++; } } TRACE( wxT("DeinitHandles: %ld handles not released"), Waste ); #endif // dealloc the memory we now have from the OS HandlesMemory.DeInit(); }

ADDR DescribeHandle (  MHANDLE  Handle  )

To get an up to date location of the memory location. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 27/04/93 Parameters: A  Handle to a memory location [INPUTS] Returns: The address associated with the handle supplied Definition at line 242 of file handles.cpp. { #ifdef USE_UNIQUE_IDS ENSURE( (Handle & 0xFFFF) > BAD_MHANDLE, "DescribeHandle: Handle was Bad" ); ENSURE( (Handle & 0xFFFF) < ElementsInHandleTable, "DescribeHandle: Handle out of range" ); #else ENSURE(Handle > BAD_MHANDLE, "DescribeHandle: Handle was Bad" ); ENSURE(Handle < ElementsInHandleTable, "DescribeHandle: Handle out of range" ); #endif // passed all the assertions, but make no checks that the addr being returned // is valid. If it is not then they will be passed BAD_MHANDLE // Must also check that the Unique ID in the Handle is the same as the one in the // Handle table, but only if USE_UNIQUE_IDS is defined #ifdef USE_UNIQUE_IDS // Have to decode the handles if ((HIWORD(Handle)) != (HandlesTable[LOWORD(Handle)].UniqueID)) return BAD_MHANDLE; else return HandlesTable[LOWORD(Handle)].Address; #else // the more efficent version, with no unique ID passing return HandlesTable[Handle].Address; #endif }

BOOL InitHandles (   )

Starts up the Handles stuff. It sets all the handles in the table to sensible starting values and inits a count of the number of handles. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 27/04/93 Returns: TRUE if all went OK, FALSE otherwise Definition at line 159 of file handles.cpp. { // Try and get some memory from the OS for my lovely table HandleTableTotalSize = HandleTableByteSize; ElementsInHandleTable = HandleTableSize; HandlesInUse = 0; HandlesTable = (HandleTableElement*) HandlesMemory.Init( HandleTableTotalSize, TRUE, MEMORYBLOCK_RELOCHEAP); // check to see if we got the ram needed if (HandlesTable==NULL) return FALSE; // init all the elements in the table to a non-existent handle for (UINT32 n=0; n<ElementsInHandleTable; n++) { // Set the Address to Bad HandlesTable[n].Address = PBYTE(BAD_MHANDLE); // if we are using unique IDs, set it to zero #ifdef USE_UNIQUE_IDS HandlesTable[n].UniqueID = 0; #endif } // All worked return TRUE; }

BOOL ReleaseHandle (  MHANDLE  Handle  )

To free up a handle that is no longer required by its user Notes: There are 2 versions of this function below - one is used if USE_UNIQUE_IDS is defined and the other if it is not. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 27/04/93 Parameters: A  Handle that is currently in use [INPUTS] Returns: A BOOL to say if the release of the Handle was succesful Definition at line 323 of file handles.cpp. { // TRACEUSER("Gerry", _T("ReleaseHandle - %d"), Handle); // make sure its not garbage ENSURE( Handle > BAD_MHANDLE, "ReleaseHandle: Handle was BAD_MHANDLE" ); ENSURE( Handle < ElementsInHandleTable, "ReleaseHandle: Handle was too big" ); if ( HandlesTable[Handle].Address != BAD_MHANDLE ) { // mark it as available HandlesTable[Handle].Address = PBYTE(BAD_MHANDLE); HandlesInUse --; return TRUE; } return FALSE; // if we got here, return false }

BOOL ReleaseRangeOfHandles (  ADDR  LowAddr, ADDR  HighAddr )

Find all the handles that refer to address in the the given range and release them. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 28/04/93 Parameters: LowAddr  - The Low address in the range [INPUTS] HighAddr - The High address in the range to be searched Returns: TRUE Definition at line 455 of file handles.cpp. { // TRACEUSER("Gerry", _T("ReleaseRange - 0x%08x to 0x%08x"), LowAddr, HighAddr); // Make sure the params are not rubbish ENSURE( HighAddr > LowAddr, "ReleaseRangeOfHandles: Low Addr is Higher the High Addr" ); // loop through the table ADDR Address; for (UINT32 n=1; n<ElementsInHandleTable; n++) { // First out get the address from the array Address = HandlesTable[ n ].Address; // if it is ok if (Address != BAD_MHANDLE) { if( Address >= LowAddr && Address < HighAddr ) { // If the address is in the range, release it // TRACEUSER("Gerry", _T("ReleaseRange - releasing %d"), n); HandlesTable[n].Address = PBYTE(BAD_MHANDLE); HandlesInUse --; } } } return TRUE; }

BOOL RelocateHandles (  ADDR  LowAddr, ADDR  HighAddr, INT32  Shift )

Finds all the memory locations in the supplied region that have handles associated with them and modifies the address. Usually called by the memory manager when it shifts a block of memory to a different location. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 27/04/93 Parameters: LowAddr  - The low address in the region supplied [INPUTS] HighAddr - The high address in the region supplied Shift - The amount to alter all the address in the region by. Returns: TRUE Definition at line 411 of file handles.cpp. { // Make sure that the params are not rubbish ENSURE( HighAddr > LowAddr, "RelocateHandles: Low Addr is Higher the High Addr" ); // Check if nothing needs to be done if (Shift == 0) return TRUE; // Loop through the handles ADDR Address; for (UINT32 n=1; n<ElementsInHandleTable; n++) { // First out get the address from the array Address = HandlesTable[n].Address; if (Address != BAD_MHANDLE) { if (Address >= LowAddr && Address < HighAddr) // If the address is in the range, shift it and store it back in the array HandlesTable[n].Address = Address + Shift; } } return TRUE; }

---

Variable Documentation

const MHANDLE BAD_MHANDLE = MHANDLE(NULL)

Definition at line 118 of file handles.h.

---