|
|
udi_buf_best_path(3udi)
Select best path(s) for a data buffer
#include <udi.h>void udi_buf_best_path ( udi_buf_t *buf, udi_buf_path_t *path_handles, udi_ubit8_t npaths, udi_ubit8_t last_fit, udi_ubit8_t *best_fit_array ); /* Terminator for best_fit_array */#define UDI_BUF_PATH_END 255ARGUMENTS buf is a pointer to a UDI data buffer.
path_handles is an array of candidate buffer path handles which correspond to parent instances to which the buffer might be sent..
npaths is the number of entries to use from the path_handles array. npaths must be greater than zero and less than 256.
last_fit is an index into the path_handles array (starting from zero) indicating the least preferred choice (typically, the one that was selected last time). last_fit must be less than npaths.
best_fit_array is an array of index values, which is filled in with the indices of one or more path_handles entries that best fit the data buffer. The list is terminated with an entry containing UDI_BUF_PATH_END. best_fit_array must point to enough space for (npaths+1) entries.
DESCRIPTION udi_buf_best_path is used to choose between multiple alternative path handles, each associated with a particular data path over which a request might be sent, and find those that can be expected to result in the best performance, all other aspects of the data path being equal. The environment may consider multiple choices to be equally suitable, and thus the result is returned as a list, in best_fit_array.
Some drivers may wish to factor in other criteria to further narrow down the choice; such drivers would scan the entire returned list. Others may simply take the first entry in best_fit_array, unconditionally. In the latter case, these drivers may want to load-balance among the otherwise-equal alternatives; this is achieved by setting last_fit to the index that was chosen in the previous call to udi_buf_best_best_path.
The index values returned in best_fit_array are provided in ascending order starting from the first one that is strictly greater than last_fit modulo npaths, and wrapping around once npaths is reached.