/* ********************************************************** * Copyright 2008 - 2010 VMware, Inc. All rights reserved. * **********************************************************/ /* * @VMKAPIMOD_LICENSE@ */ /* *********************************************************************** * HelperWorlds */ /** * \defgroup HelperWorlds Helper Worlds * * Helper Worlds are a mechanism that allows work to be queued and * run by a dynamically managed pool of worlds. * * @{ *********************************************************************** */ #ifndef _VMKAPI_HELPER_WORLDS_H_ #define _VMKAPI_HELPER_WORLDS_H_ /** \cond never */ #ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H #error This vmkapi file should never be included directly but only via vmkapi.h #endif #ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H #error This vmkapi file should never be included directly but only via vmkapi.h #endif /** \endcond never */ /** Invalid helper ID */ #define VMK_HELPER_INVALID_ID ((vmk_Helper)-1) /** Use default request properties */ #define VMK_HELPER_DEFAULT_REQ_PROPS ((const vmk_HelperRequestProps *)NULL) /* Opaque helper definition */ typedef vmk_uintptr_t vmk_Helper; /* *********************************************************************** * vmk_HelperTagComparator -- */ /** * * \ingroup HelperWorlds * \brief Compare two request tags to see if they are equal * * This function is used to find a request or set of requests based * on their tag, such as during cancellation. * * \note Callbacks of this type may not block. * * \param[in] tag1 First tag to compare. * \param[in] tag2 Second tag to compare. * * \retval VMK_TRUE The tags match. * \retval VMK_FALSE The tags do not match. * *********************************************************************** */ typedef vmk_Bool (*vmk_HelperTagComparator)(vmk_AddrCookie tag1, vmk_AddrCookie tag2); /* *********************************************************************** * vmk_HelperConstructor -- */ /** * * \ingroup HelperWorlds * \brief Function invoked when a new helper world is spawned. * * \note Callbacks of this type may not block. * * \param[in] arg Constructor argument that was stored in the helper * queue's properties. * *********************************************************************** */ typedef void (*vmk_HelperConstructor)(vmk_AddrCookie arg); /* *********************************************************************** * vmk_HelperCancelFunc -- */ /** * * \ingroup HelperWorlds * \brief Function invoked when a request is canceled. * * \note Callbacks of this type may not block. * * \param[in] data Data that was passed in with the request. * *********************************************************************** */ typedef void (*vmk_HelperCancelFunc)(vmk_AddrCookie data); /* *********************************************************************** * vmk_HelperRequestFunc -- */ /** * * \ingroup HelperWorlds * \brief Function invoked when a request is processed * * \note Callbacks of this type may not block. * * \param[in] data Data that was passed in with the request. * *********************************************************************** */ typedef void (*vmk_HelperRequestFunc)(vmk_AddrCookie data); /** * \brief Properties for a helper queue that may be updated * after it is created. */ typedef struct vmk_HelperMutableProps { /** * Minimum number of worlds that will continue to exist to serve * the helper queue. * * Setting this to a value less than the value of maxWorlds indicates * that the helper queue can dynamically create and destroy worlds for * the helper queue but will always maintain at least the specified * number of worlds in the queue. * * Setting this to -1 or the same value as maxWorlds indicates that * the caller does not want helper worlds to exit and does not want * the pool of worlds to shrink dynamically. */ vmk_int32 minWorlds; /** * Maximum number of worlds that will service the helper queue. * * Setting this to 0 or less indicates that the helper queue should * use the default number of worlds to service the helper queue. * * Setting this to 1 or more indicates that the helper queue should * use the specified number of worlds as the maximum number of worlds * that can back the queue. */ vmk_int32 maxWorlds; /** * Maximum number of milliseconds a world backing the helper * queue can be idle before it is retired. * * Setting this to 0 or less indicates that the default idle time * should be used. * * Setting this to 1 or more indiciates that if a world in the pool * backing the helper queue has been idle for the specified number * of milliseconds it will be retired. */ vmk_int32 maxIdleTime; /** * Maximum number of milliseconds a request can wait in the * queue before a new world will be created to service the request. * * Setting this to 0 or less indiciates that the helper queue should * use the default time. * * Setting this to 1 or more indicates that after the specified number * of milliseconds a new world will be added to the pool of worlds * backing the helper queue. * * \note The specified maximum number of worlds will not be * exceeded even if a request has been waiting longer * than the specified time. */ vmk_int32 maxRequestBlockTime; } vmk_HelperMutableProps; /** * \brief Properties for a new helper queue */ typedef struct { /** Human readable name for the helper queue */ vmk_Name name; /** A heap the helper can use for allocations */ vmk_HeapID heap; /** * Should an IRQ spinlock should be used when synchronizing * between producers and consumers of the helper queue? */ vmk_Bool useIrqSpinlock; /** * Should all memory for requests be preallocated when * the helper queue is created? */ vmk_Bool preallocRequests; /** * Can callers block when submitting requests? * Callers can override this setting on a per-call basis. */ vmk_Bool blockingSubmit; /** * Maximum number of requests this queue can support */ vmk_uint32 maxRequests; /** * Initial setting for properties which may be updated after * the helper queue is created. */ vmk_HelperMutableProps mutables; /** * Function to compare two tags that identify requests * * Can be set to NULL if no function is desired. */ vmk_HelperTagComparator tagCompare; /** * Function to call when a new world is added to the * pool of worlds backing the helper queue. * * This function will run in the context of the * new world. * * This function will be called before running * any helper requests on the new world. * * This can be set to NULL if no function is desired. */ vmk_HelperConstructor constructor; /** Data to pass to the constructor function */ vmk_AddrCookie constructorArg; } vmk_HelperProps; /** * \brief Properties for a helper request */ typedef struct vmk_HelperRequestProps { /** Should the submission of this request block the caller? */ vmk_Bool requestMayBlock; /** * A caller-supplied tag to identify the request. * * This tag is used to identify the request for calls * such as vmk_HelperCancelRequest(). */ vmk_AddrCookie tag; /** * An optional function to call after a request is canceled * to perform cleanup. * * May be set to NULL if no function is required. * * This field cannot be set if the tag field is set to zero. */ vmk_HelperCancelFunc cancelFunc; /** * World to which to bill helper work or VMK_INVALID_WORLD_ID * if there is no world to bill. */ vmk_WorldID worldToBill; } vmk_HelperRequestProps; /* *********************************************************************** * vmk_HelperCreate -- */ /** * * \ingroup HelperWorlds * \brief Create a new helper world queue. * * \note This function may block. * * \param[in] props Creation properties for the new helper queue. * \param[out] helper The newly created helper queue. * * * *********************************************************************** */ VMK_ReturnStatus vmk_HelperCreate(vmk_HelperProps *props, vmk_Helper *helper); /* *********************************************************************** * vmk_HelperDestroy -- */ /** * * \ingroup HelperWorlds * \brief Destroy an existing helper world queue. * * \note This function may block. * * \param[in] helper Helper queue to destroy. * *********************************************************************** */ VMK_ReturnStatus vmk_HelperDestroy(vmk_Helper helper); /* *********************************************************************** * vmk_HelperUpdateProps -- */ /** * * \ingroup HelperWorlds * \brief Update the mutable properties on an existing helper queue. * * \note This function will not block. * * \param[in] helper Helper queue to destroy. * \param[in] props New properties for the helper queue. * *********************************************************************** */ VMK_ReturnStatus vmk_HelperUpdateProps(vmk_Helper helper, const vmk_HelperMutableProps *props); /* *********************************************************************** * vmk_HelperRequestPropsInit -- */ /** * * \ingroup HelperWorlds * \brief Initialize a vmk_HelperRequestProps structure. * * The resulting structure will have all properties set to their default. * * \note This function will not block. * * \param[in] props Pointer to the parameters to initialize. * * \retval VMK_INVALID_NAME Name for the helper queue is too long * *********************************************************************** */ void vmk_HelperRequestPropsInit(vmk_HelperRequestProps *props); /* *********************************************************************** * vmk_HelperSubmitRequest -- */ /** * * \ingroup HelperWorlds * \brief Submit a request to a helper world queue to be executed later * * \note This function may block if the queue has been created with * blocking properties. * * \param[in] helper Helper queue to send the request to. * \param[in] requestFunc Function to execute * \param[in] data Data to pass to the function that will be * executed. * \param[in] props Properties of this request submission; * use vmk_HelperRequestPropsInit if the default * parameters are desired. * *********************************************************************** */ VMK_ReturnStatus vmk_HelperSubmitRequest(vmk_Helper helper, vmk_HelperRequestFunc requestFunc, vmk_AddrCookie data, const vmk_HelperRequestProps *props); /* *********************************************************************** * vmk_HelperSubmitDelayedRequest -- */ /** * * \ingroup HelperWorlds * \brief Submit a request to a helper world queue to be executed only * after a specified amount of time. * * \note This function may block if the queue has been created with * blocking properties. * * \param[in] helper Helper queue to send the request to. * \param[in] requestFunc Function to execute * \param[in] data Data to pass to the function that will be * executed. * \param[in] props Properties of this request submission; * use vmk_HelperRequestPropsInit if the default * parameters are desired. * \param[in] timeoutMS Timeout in millseconds after which the function * would be executed by the helper. * *********************************************************************** */ VMK_ReturnStatus vmk_HelperSubmitDelayedRequest(vmk_Helper helper, vmk_HelperRequestFunc requestFunc, vmk_AddrCookie data, vmk_uint32 timeoutMS, const vmk_HelperRequestProps *props); /* *********************************************************************** * vmk_HelperCancelRequest -- */ /** * * \ingroup HelperWorlds * \brief Cancel requests on the queue that have the specified tag. * * \note This function may block if the queue has been created with * blocking properties. * * \param[in] helper Helper queue on which to issue the cancel. * \param[in] requestTag Tag used to identify which requests to * cancel. * \param[out] numCancelled Number of requests that were actually * cancelled. * *********************************************************************** */ VMK_ReturnStatus vmk_HelperCancelRequest(vmk_Helper helper, vmk_AddrCookie requestTag, vmk_uint32 *numCancelled); /* *********************************************************************** * vmk_HelperCurrentRequestCount -- */ /** * * \ingroup HelperWorlds * \brief Get a snapshot of the current number of pending requests on * a helper queue. * * \note The count returned by this function does not include the * count of requests that are actively being processed. * * \note This function will not block. * * \param[in] helper Helper queue to check. * * \return The number of pending requests on the helper queue. * *********************************************************************** */ vmk_uint32 vmk_HelperCurrentRequestCount(vmk_Helper helper); #endif /* _VMKAPI_HELPER_WORLDS_H_ */ /** @} */