tmm_cache_entry_find()
Note: Requires Terrain Modeling Module functionality
Abstract
Determines if there is an entry in a TmmT_Cache data structure that matches the specified positions and returns the entry.
Syntax
tmm_cache_entry_find (cache_ptr, entry_key_ptr)
| Argument | Type | Description |
|---|---|---|
cache_ptr |
TmmT_Loss_Cache* |
pointer to the cache in which to search. |
entry_key_ptr |
TmmT_Cache_Entry * |
pointer to a user-created entry containing the positions to be found in the cache. |
Return Value
Boolean
Returns OPC_TRUE if a match to the specified positions is found, and changes the loss_value, value_status, and msg_v[] values in the data structure pointed to by entry_key_ptr to those found in the matching cache entry. If no match is found, returns OPC_FALSE.
Header
tmm.h
Example
TmmT_Cache_Entry loss_entry;
/* prepare the key used to search the cache with */
/* our Tx/Rx positions and heights */
loss_entry.tx_quantized_position = *tx_pos_ptr;
loss_entry.rx_quantized_position = *rx_pos_ptr;
/* Search cache for a value that has already been computed */
if (tmm_cache_entry_find (cache_ptr, &loss_entry) == OPC_FALSE)
{
/* Do work needed to calculate the loss */
...
}
else
{
/* A value was found in the cache. */
/* _find fills the "loss_entry" structure with values */
*status_ptr = loss_entry.value_status;
}
FRET (loss_cache_entry.loss_value)
Details
In order to limit the number of times path loss is calculated during a simulation, a data structure (a cache) containing all previous positions of the transmitter and receiver antenna pair is created. If the antennas are mobile and move between transmissions, the new positions are looked up in the cache. If there is a match, the application uses the path loss stored in the cache for the corresponding antenna location, instead of recalculating the path loss.
For a match to occur, each new position must be close to a position in a cache entry. How "close" it must be is determined by the position and height tolerances specified when the cache was created with tmm_cache_create().
The positions to be found should be in a data structure of type TmmT_Cache_Entry. The contents of this structure are the same as an individual cache entry, as shown in the Details section of tmm_cache_create(). If a match is found, this function puts the found values of loss_value and value_status into the data structure specified in the call.
Purpose
This function is used to search a specified cache to determine if a path loss has been previously calculated for the specified positions. If so, the path loss is returned.
Errors
- Cache argument is invalid. Check that your cache hasn't been passed to tmm_cache_destroy().
- Pointer to Entry key data structure is NULL. You should be calling
tmm_cache_entry_find()with a cache and the address of a TmmT_Cache_Entry.
Reference
- Use the function tmm_cache_create() to create a new cache.
- Use the function tmm_cache_destroy() to destroy a specified cache.
- Use the function tmm_cache_entry_add() to add path loss information for a specific position pair to the TmmT_cache data structure.