1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * Declaration of dispatcher abstraction. 39219820Sjeff */ 40219820Sjeff 41219820Sjeff#ifndef _CL_DISPATCHER_H_ 42219820Sjeff#define _CL_DISPATCHER_H_ 43219820Sjeff 44219820Sjeff#include <complib/cl_atomic.h> 45219820Sjeff#include <complib/cl_threadpool.h> 46219820Sjeff#include <complib/cl_qlist.h> 47219820Sjeff#include <complib/cl_qpool.h> 48219820Sjeff#include <complib/cl_spinlock.h> 49219820Sjeff#include <complib/cl_ptr_vector.h> 50219820Sjeff 51219820Sjeff#ifdef __cplusplus 52219820Sjeff# define BEGIN_C_DECLS extern "C" { 53219820Sjeff# define END_C_DECLS } 54219820Sjeff#else /* !__cplusplus */ 55219820Sjeff# define BEGIN_C_DECLS 56219820Sjeff# define END_C_DECLS 57219820Sjeff#endif /* __cplusplus */ 58219820Sjeff 59219820SjeffBEGIN_C_DECLS 60219820Sjeff/****h* Component Library/Dispatcher 61219820Sjeff* NAME 62219820Sjeff* Dispatcher 63219820Sjeff* 64219820Sjeff* DESCRIPTION 65219820Sjeff* The Dispatcher provides a facility for message routing to 66219820Sjeff* asynchronous worker threads. 67219820Sjeff* 68219820Sjeff* The Dispatcher functions operate on a cl_dispatcher_t structure 69219820Sjeff* which should be treated as opaque and should be manipulated 70219820Sjeff* only through the provided functions. 71219820Sjeff* 72219820Sjeff* SEE ALSO 73219820Sjeff* Structures: 74219820Sjeff* cl_dispatcher_t 75219820Sjeff* 76219820Sjeff* Initialization/Destruction: 77219820Sjeff* cl_disp_construct, cl_disp_init, cl_disp_shutdown, cl_disp_destroy 78219820Sjeff* 79219820Sjeff* Manipulation: 80219820Sjeff* cl_disp_post, cl_disp_reset, cl_disp_wait_on 81219820Sjeff*********/ 82219820Sjeff/****s* Component Library: Dispatcher/cl_disp_msgid_t 83219820Sjeff* NAME 84219820Sjeff* cl_disp_msgid_t 85219820Sjeff* 86219820Sjeff* DESCRIPTION 87219820Sjeff* Defines the type of dispatcher messages. 88219820Sjeff* 89219820Sjeff* SYNOPSIS 90219820Sjeff*/ 91219820Sjefftypedef uint32_t cl_disp_msgid_t; 92219820Sjeff/**********/ 93219820Sjeff 94219820Sjeff/****s* Component Library: Dispatcher/CL_DISP_MSGID_NONE 95219820Sjeff* NAME 96219820Sjeff* CL_DISP_MSGID_NONE 97219820Sjeff* 98219820Sjeff* DESCRIPTION 99219820Sjeff* Defines a message value that means "no message". 100219820Sjeff* This value is used during registration by Dispatcher clients 101219820Sjeff* that do not wish to receive messages. 102219820Sjeff* 103219820Sjeff* No Dispatcher message is allowed to have this value. 104219820Sjeff* 105219820Sjeff* SYNOPSIS 106219820Sjeff*/ 107219820Sjeff#define CL_DISP_MSGID_NONE 0xFFFFFFFF 108219820Sjeff/**********/ 109219820Sjeff 110219820Sjeff/****s* Component Library: Dispatcher/CL_DISP_INVALID_HANDLE 111219820Sjeff* NAME 112219820Sjeff* CL_DISP_INVALID_HANDLE 113219820Sjeff* 114219820Sjeff* DESCRIPTION 115219820Sjeff* Defines the value of an invalid Dispatcher registration handle. 116219820Sjeff* 117219820Sjeff* SYNOPSIS 118219820Sjeff*/ 119219820Sjeff#define CL_DISP_INVALID_HANDLE ((cl_disp_reg_handle_t)0) 120219820Sjeff/*********/ 121219820Sjeff 122219820Sjeff/****f* Component Library: Dispatcher/cl_pfn_msgrcv_cb_t 123219820Sjeff* NAME 124219820Sjeff* cl_pfn_msgrcv_cb_t 125219820Sjeff* 126219820Sjeff* DESCRIPTION 127219820Sjeff* This typedef defines the prototype for client functions invoked 128219820Sjeff* by the Dispatcher. The Dispatcher calls the corresponding 129219820Sjeff* client function when delivering a message to the client. 130219820Sjeff* 131219820Sjeff* The client function must be reentrant if the user creates a 132219820Sjeff* Dispatcher with more than one worker thread. 133219820Sjeff* 134219820Sjeff* SYNOPSIS 135219820Sjeff*/ 136219820Sjefftypedef void 137219820Sjeff (*cl_pfn_msgrcv_cb_t) (IN void *context, IN void *p_data); 138219820Sjeff/* 139219820Sjeff* PARAMETERS 140219820Sjeff* context 141219820Sjeff* [in] Client specific context specified in a call to 142219820Sjeff* cl_disp_register 143219820Sjeff* 144219820Sjeff* p_data 145219820Sjeff* [in] Pointer to the client specific data payload 146219820Sjeff* of this message. 147219820Sjeff* 148219820Sjeff* RETURN VALUE 149219820Sjeff* This function does not return a value. 150219820Sjeff* 151219820Sjeff* NOTES 152219820Sjeff* This typedef provides a function prototype reference for 153219820Sjeff* the function provided by Dispatcher clients as a parameter 154219820Sjeff* to the cl_disp_register function. 155219820Sjeff* 156219820Sjeff* SEE ALSO 157219820Sjeff* Dispatcher, cl_disp_register 158219820Sjeff*********/ 159219820Sjeff 160219820Sjeff/****f* Component Library: Dispatcher/cl_pfn_msgdone_cb_t 161219820Sjeff* NAME 162219820Sjeff* cl_pfn_msgdone_cb_t 163219820Sjeff* 164219820Sjeff* DESCRIPTION 165219820Sjeff* This typedef defines the prototype for client functions invoked 166219820Sjeff* by the Dispatcher. The Dispatcher calls the corresponding 167219820Sjeff* client function after completing delivery of a message. 168219820Sjeff* 169219820Sjeff* The client function must be reentrant if the user creates a 170219820Sjeff* Dispatcher with more than one worker thread. 171219820Sjeff* 172219820Sjeff* SYNOPSIS 173219820Sjeff*/ 174219820Sjefftypedef void 175219820Sjeff (*cl_pfn_msgdone_cb_t) (IN void *context, IN void *p_data); 176219820Sjeff/* 177219820Sjeff* PARAMETERS 178219820Sjeff* context 179219820Sjeff* [in] Client specific context specified in a call to 180219820Sjeff* cl_disp_post 181219820Sjeff* 182219820Sjeff* p_data 183219820Sjeff* [in] Pointer to the client specific data payload 184219820Sjeff* of this message. 185219820Sjeff* 186219820Sjeff* RETURN VALUE 187219820Sjeff* This function does not return a value. 188219820Sjeff* 189219820Sjeff* NOTES 190219820Sjeff* This typedef provides a function prototype reference for 191219820Sjeff* the function provided by Dispatcher clients as a parameter 192219820Sjeff* to the cl_disp_post function. 193219820Sjeff* 194219820Sjeff* SEE ALSO 195219820Sjeff* Dispatcher, cl_disp_post 196219820Sjeff*********/ 197219820Sjeff 198219820Sjeff/****s* Component Library: Dispatcher/cl_dispatcher_t 199219820Sjeff* NAME 200219820Sjeff* cl_dispatcher_t 201219820Sjeff* 202219820Sjeff* DESCRIPTION 203219820Sjeff* Dispatcher structure. 204219820Sjeff* 205219820Sjeff* The Dispatcher is thread safe. 206219820Sjeff* 207219820Sjeff* The cl_dispatcher_t structure should be treated as opaque and should 208219820Sjeff* be manipulated only through the provided functions. 209219820Sjeff* 210219820Sjeff* SYNOPSIS 211219820Sjeff*/ 212219820Sjefftypedef struct _cl_dispatcher { 213219820Sjeff cl_spinlock_t lock; 214219820Sjeff cl_ptr_vector_t reg_vec; 215219820Sjeff cl_qlist_t reg_list; 216219820Sjeff cl_thread_pool_t worker_threads; 217219820Sjeff cl_qlist_t msg_fifo; 218219820Sjeff cl_qpool_t msg_pool; 219219820Sjeff uint64_t last_msg_queue_time_us; 220219820Sjeff} cl_dispatcher_t; 221219820Sjeff/* 222219820Sjeff* FIELDS 223219820Sjeff* reg_vec 224219820Sjeff* Vector of registration info objects. Indexed by message msg_id. 225219820Sjeff* 226219820Sjeff* lock 227219820Sjeff* Spinlock to guard internal structures. 228219820Sjeff* 229219820Sjeff* msg_fifo 230219820Sjeff* FIFO of messages being processed by the Dispatcher. New 231219820Sjeff* messages are posted to the tail of the FIFO. Worker threads 232219820Sjeff* pull messages from the front. 233219820Sjeff* 234219820Sjeff* worker_threads 235219820Sjeff* Thread pool of worker threads to dispose of posted messages. 236219820Sjeff* 237219820Sjeff* msg_pool 238219820Sjeff* Pool of message objects to be processed through the FIFO. 239219820Sjeff* 240219820Sjeff* reg_count 241219820Sjeff* Count of the number of registrants. 242219820Sjeff* 243219820Sjeff* state 244219820Sjeff* Indicates the state of the object. 245219820Sjeff* 246219820Sjeff* last_msg_queue_time_us 247219820Sjeff* The time that the last message spent in the Q in usec 248219820Sjeff* 249219820Sjeff* SEE ALSO 250219820Sjeff* Dispatcher 251219820Sjeff*********/ 252219820Sjeff 253219820Sjeff/****s* Component Library: Dispatcher/cl_disp_reg_info_t 254219820Sjeff* NAME 255219820Sjeff* cl_disp_reg_info_t 256219820Sjeff* 257219820Sjeff* DESCRIPTION 258219820Sjeff* Defines the dispatcher registration object structure. 259219820Sjeff* 260219820Sjeff* The cl_disp_reg_info_t structure is for internal use by the 261219820Sjeff* Dispatcher only. 262219820Sjeff* 263219820Sjeff* SYNOPSIS 264219820Sjeff*/ 265219820Sjefftypedef struct _cl_disp_reg_info { 266219820Sjeff cl_list_item_t list_item; 267219820Sjeff cl_pfn_msgrcv_cb_t pfn_rcv_callback; 268219820Sjeff const void *context; 269219820Sjeff atomic32_t ref_cnt; 270219820Sjeff cl_disp_msgid_t msg_id; 271219820Sjeff cl_dispatcher_t *p_disp; 272219820Sjeff} cl_disp_reg_info_t; 273219820Sjeff/* 274219820Sjeff* FIELDS 275219820Sjeff* pfn_rcv_callback 276219820Sjeff* Client's message receive callback. 277219820Sjeff* 278219820Sjeff* context 279219820Sjeff* Client's context for message receive callback. 280219820Sjeff* 281219820Sjeff* rcv_thread_count 282219820Sjeff* Number of threads currently in the receive callback. 283219820Sjeff* 284219820Sjeff* msg_done_thread_count 285219820Sjeff* Number of threads currently in the message done callback. 286219820Sjeff* 287219820Sjeff* state 288219820Sjeff* State of this registration object. 289219820Sjeff* DISP_REGSTATE_INIT: initialized and inactive 290219820Sjeff* DISP_REGSTATE_ACTIVE: in active use 291219820Sjeff* DISP_REGSTATE_UNREGPEND: unregistration is pending 292219820Sjeff* 293219820Sjeff* msg_id 294219820Sjeff* Dispatcher message msg_id value for this registration object. 295219820Sjeff* 296219820Sjeff* p_disp 297219820Sjeff* Pointer to parent Dispatcher. 298219820Sjeff* 299219820Sjeff* SEE ALSO 300219820Sjeff*********/ 301219820Sjeff 302219820Sjeff/****s* Component Library: Dispatcher/cl_disp_msg_t 303219820Sjeff* NAME 304219820Sjeff* cl_disp_msg_t 305219820Sjeff* 306219820Sjeff* DESCRIPTION 307219820Sjeff* Defines the dispatcher message structure. 308219820Sjeff* 309219820Sjeff* The cl_disp_msg_t structure is for internal use by the 310219820Sjeff* Dispatcher only. 311219820Sjeff* 312219820Sjeff* SYNOPSIS 313219820Sjeff*/ 314219820Sjefftypedef struct _cl_disp_msg { 315219820Sjeff cl_pool_item_t item; 316219820Sjeff const void *p_data; 317219820Sjeff cl_disp_reg_info_t *p_src_reg; 318219820Sjeff cl_disp_reg_info_t *p_dest_reg; 319219820Sjeff cl_pfn_msgdone_cb_t pfn_xmt_callback; 320219820Sjeff uint64_t in_time; 321219820Sjeff const void *context; 322219820Sjeff} cl_disp_msg_t; 323219820Sjeff/* 324219820Sjeff* FIELDS 325219820Sjeff* item 326219820Sjeff* List & Pool linkage. Must be first element in the structure!! 327219820Sjeff* 328219820Sjeff* msg_id 329219820Sjeff* The message's numberic ID value. 330219820Sjeff* 331219820Sjeff* p_data 332219820Sjeff* Pointer to the data payload for this message. The payload 333219820Sjeff* is opaque to the Dispatcher. 334219820Sjeff* 335219820Sjeff* p_reg_info 336219820Sjeff* Pointer to the registration info of the sender. 337219820Sjeff* 338219820Sjeff* pfn_xmt_callback 339219820Sjeff* Client's message done callback. 340219820Sjeff* 341219820Sjeff* in_time 342219820Sjeff* The absolute time the message was inserted into the queue 343219820Sjeff* 344219820Sjeff* context 345219820Sjeff* Client's message done callback context. 346219820Sjeff* 347219820Sjeff* SEE ALSO 348219820Sjeff*********/ 349219820Sjeff 350219820Sjeff/****s* Component Library: Dispatcher/cl_disp_reg_info_t 351219820Sjeff* NAME 352219820Sjeff* cl_disp_reg_info_t 353219820Sjeff* 354219820Sjeff* DESCRIPTION 355219820Sjeff* Defines the Dispatcher registration handle. This handle 356219820Sjeff* should be treated as opaque by the client. 357219820Sjeff* 358219820Sjeff* SYNOPSIS 359219820Sjeff*/ 360219820Sjefftypedef const struct _cl_disp_reg_info *cl_disp_reg_handle_t; 361219820Sjeff/**********/ 362219820Sjeff 363219820Sjeff/****f* Component Library: Dispatcher/cl_disp_construct 364219820Sjeff* NAME 365219820Sjeff* cl_disp_construct 366219820Sjeff* 367219820Sjeff* DESCRIPTION 368219820Sjeff* This function constructs a Dispatcher object. 369219820Sjeff* 370219820Sjeff* SYNOPSIS 371219820Sjeff*/ 372219820Sjeffvoid cl_disp_construct(IN cl_dispatcher_t * const p_disp); 373219820Sjeff/* 374219820Sjeff* PARAMETERS 375219820Sjeff* p_disp 376219820Sjeff* [in] Pointer to a Dispatcher. 377219820Sjeff* 378219820Sjeff* RETURN VALUE 379219820Sjeff* This function does not return a value. 380219820Sjeff* 381219820Sjeff* NOTES 382219820Sjeff* Allows calling cl_disp_init and cl_disp_destroy. 383219820Sjeff* 384219820Sjeff* SEE ALSO 385219820Sjeff* Dispatcher, cl_disp_init, cl_disp_destroy 386219820Sjeff*********/ 387219820Sjeff 388219820Sjeff/****f* Component Library: Dispatcher/cl_disp_init 389219820Sjeff* NAME 390219820Sjeff* cl_disp_init 391219820Sjeff* 392219820Sjeff* DESCRIPTION 393219820Sjeff* This function initializes a Dispatcher object. 394219820Sjeff* 395219820Sjeff* SYNOPSIS 396219820Sjeff*/ 397219820Sjeffcl_status_t 398219820Sjeffcl_disp_init(IN cl_dispatcher_t * const p_disp, 399219820Sjeff IN const uint32_t thread_count, IN const char *const name); 400219820Sjeff/* 401219820Sjeff* PARAMETERS 402219820Sjeff* p_disp 403219820Sjeff* [in] Pointer to a Dispatcher. 404219820Sjeff* 405219820Sjeff* thread_count 406219820Sjeff* [in] The number of worker threads to create in this Dispatcher. 407219820Sjeff* A value of 0 causes the Dispatcher to create one worker thread 408219820Sjeff* per CPU in the system. When the Dispatcher is created with 409219820Sjeff* only one thread, the Dispatcher guarantees to deliver posted 410219820Sjeff* messages in order. When the Dispatcher is created with more 411219820Sjeff* than one thread, messages may be delivered out of order. 412219820Sjeff* 413219820Sjeff* name 414219820Sjeff* [in] Name to associate with the threads. The name may be up to 16 415219820Sjeff* characters, including a terminating null character. All threads 416219820Sjeff* created in the Dispatcher have the same name. 417219820Sjeff* 418219820Sjeff* RETURN VALUE 419219820Sjeff* CL_SUCCESS if the operation is successful. 420219820Sjeff* 421219820Sjeff* SEE ALSO 422219820Sjeff* Dispatcher, cl_disp_destoy, cl_disp_register, cl_disp_unregister, 423219820Sjeff* cl_disp_post 424219820Sjeff*********/ 425219820Sjeff 426219820Sjeff/****f* Component Library: Dispatcher/cl_disp_shutdown 427219820Sjeff* NAME 428219820Sjeff* cl_disp_shutdown 429219820Sjeff* 430219820Sjeff* DESCRIPTION 431219820Sjeff* This function shutdown a Dispatcher object. So it unreg all messages and 432219820Sjeff* clears the fifo and waits for the threads to exit 433219820Sjeff* 434219820Sjeff* SYNOPSIS 435219820Sjeff*/ 436219820Sjeffvoid cl_disp_shutdown(IN cl_dispatcher_t * const p_disp); 437219820Sjeff/* 438219820Sjeff* PARAMETERS 439219820Sjeff* p_disp 440219820Sjeff* [in] Pointer to a Dispatcher. 441219820Sjeff* 442219820Sjeff* RETURN VALUE 443219820Sjeff* This function does not return a value. 444219820Sjeff* 445219820Sjeff* NOTES 446219820Sjeff* This function does not returns until all worker threads 447219820Sjeff* have exited client callback functions and been successfully 448219820Sjeff* shutdowned. 449219820Sjeff* 450219820Sjeff* SEE ALSO 451219820Sjeff* Dispatcher, cl_disp_construct, cl_disp_init 452219820Sjeff*********/ 453219820Sjeff 454219820Sjeff/****f* Component Library: Dispatcher/cl_disp_destroy 455219820Sjeff* NAME 456219820Sjeff* cl_disp_destroy 457219820Sjeff* 458219820Sjeff* DESCRIPTION 459219820Sjeff* This function destroys a Dispatcher object. 460219820Sjeff* 461219820Sjeff* SYNOPSIS 462219820Sjeff*/ 463219820Sjeffvoid cl_disp_destroy(IN cl_dispatcher_t * const p_disp); 464219820Sjeff/* 465219820Sjeff* PARAMETERS 466219820Sjeff* p_disp 467219820Sjeff* [in] Pointer to a Dispatcher. 468219820Sjeff* 469219820Sjeff* RETURN VALUE 470219820Sjeff* This function does not return a value. 471219820Sjeff* 472219820Sjeff* SEE ALSO 473219820Sjeff* Dispatcher, cl_disp_construct, cl_disp_init 474219820Sjeff*********/ 475219820Sjeff 476219820Sjeff/****f* Component Library: Dispatcher/cl_disp_register 477219820Sjeff* NAME 478219820Sjeff* cl_disp_register 479219820Sjeff* 480219820Sjeff* DESCRIPTION 481219820Sjeff* This function registers a client with a Dispatcher object. 482219820Sjeff* 483219820Sjeff* SYNOPSIS 484219820Sjeff*/ 485219820Sjeffcl_disp_reg_handle_t 486219820Sjeffcl_disp_register(IN cl_dispatcher_t * const p_disp, 487219820Sjeff IN const cl_disp_msgid_t msg_id, 488219820Sjeff IN cl_pfn_msgrcv_cb_t pfn_callback OPTIONAL, 489219820Sjeff IN const void *const context); 490219820Sjeff/* 491219820Sjeff* PARAMETERS 492219820Sjeff* p_disp 493219820Sjeff* [in] Pointer to a Dispatcher. 494219820Sjeff* 495219820Sjeff* msg_id 496219820Sjeff* [in] Numberic message ID for which the client is registering. 497219820Sjeff* If the client does not wish to receive any messages, 498219820Sjeff* (a send-only client) then the caller should set this value 499219820Sjeff* to CL_DISP_MSGID_NONE. For efficiency, numeric message msg_id 500219820Sjeff* values should start with 0 and should be contiguous, or nearly so. 501219820Sjeff* 502219820Sjeff* pfn_callback 503219820Sjeff* [in] Message receive callback. The Dispatcher calls this 504219820Sjeff* function after receiving a posted message with the 505219820Sjeff* appropriate message msg_id value. Send-only clients may specify 506219820Sjeff* NULL for this value. 507219820Sjeff* 508219820Sjeff* context 509219820Sjeff* [in] Client context value passed to the cl_pfn_msgrcv_cb_t 510219820Sjeff* function. 511219820Sjeff* 512219820Sjeff* RETURN VALUE 513219820Sjeff* On success a Dispatcher registration handle. 514219820Sjeff* CL_CL_DISP_INVALID_HANDLE otherwise. 515219820Sjeff* 516219820Sjeff* SEE ALSO 517219820Sjeff* Dispatcher, cl_disp_unregister, cl_disp_post 518219820Sjeff*********/ 519219820Sjeff 520219820Sjeff/****f* Component Library: Dispatcher/cl_disp_unregister 521219820Sjeff* NAME 522219820Sjeff* cl_disp_unregister 523219820Sjeff* 524219820Sjeff* DESCRIPTION 525219820Sjeff* This function unregisters a client from a Dispatcher. 526219820Sjeff* 527219820Sjeff* SYNOPSIS 528219820Sjeff*/ 529219820Sjeffvoid cl_disp_unregister(IN const cl_disp_reg_handle_t handle); 530219820Sjeff/* 531219820Sjeff* PARAMETERS 532219820Sjeff* handle 533219820Sjeff* [in] cl_disp_reg_handle_t value return by cl_disp_register. 534219820Sjeff* 535219820Sjeff* RETURN VALUE 536219820Sjeff* This function does not return a value. 537219820Sjeff* 538219820Sjeff* NOTES 539219820Sjeff* This function will not return until worker threads have exited 540219820Sjeff* the callback functions for this client. Do not invoke this 541219820Sjeff* function from a callback. 542219820Sjeff* 543219820Sjeff* SEE ALSO 544219820Sjeff* Dispatcher, cl_disp_register 545219820Sjeff*********/ 546219820Sjeff 547219820Sjeff/****f* Component Library: Dispatcher/cl_disp_post 548219820Sjeff* NAME 549219820Sjeff* cl_disp_post 550219820Sjeff* 551219820Sjeff* DESCRIPTION 552219820Sjeff* This function posts a message to a Dispatcher object. 553219820Sjeff* 554219820Sjeff* SYNOPSIS 555219820Sjeff*/ 556219820Sjeffcl_status_t 557219820Sjeffcl_disp_post(IN const cl_disp_reg_handle_t handle, 558219820Sjeff IN const cl_disp_msgid_t msg_id, 559219820Sjeff IN const void *const p_data, 560219820Sjeff IN cl_pfn_msgdone_cb_t pfn_callback OPTIONAL, 561219820Sjeff IN const void *const context); 562219820Sjeff/* 563219820Sjeff* PARAMETERS 564219820Sjeff* handle 565219820Sjeff* [in] cl_disp_reg_handle_t value return by cl_disp_register. 566219820Sjeff* 567219820Sjeff* msg_id 568219820Sjeff* [in] Numeric message msg_id value associated with this message. 569219820Sjeff* 570219820Sjeff* p_data 571219820Sjeff* [in] Data payload for this message. 572219820Sjeff* 573219820Sjeff* pfn_callback 574219820Sjeff* [in] Pointer to a cl_pfn_msgdone_cb_t function. 575219820Sjeff* The Dispatcher calls this function after the message has been 576219820Sjeff* processed by the recipient. 577219820Sjeff* The caller may pass NULL for this value, which indicates no 578219820Sjeff* message done callback is necessary. 579219820Sjeff* 580219820Sjeff* context 581219820Sjeff* [in] Client context value passed to the cl_pfn_msgdone_cb_t 582219820Sjeff* function. 583219820Sjeff* 584219820Sjeff* RETURN VALUE 585219820Sjeff* CL_SUCCESS if the message was successfully queued in the Dispatcher. 586219820Sjeff* 587219820Sjeff* NOTES 588219820Sjeff* The caller must not modify the memory pointed to by p_data until 589219820Sjeff* the Dispatcher call the pfn_callback function. 590219820Sjeff* 591219820Sjeff* SEE ALSO 592219820Sjeff* Dispatcher 593219820Sjeff*********/ 594219820Sjeff 595219820Sjeff/****f* Component Library: Dispatcher/cl_disp_get_queue_status 596219820Sjeff* NAME 597219820Sjeff* cl_disp_get_queue_status 598219820Sjeff* 599219820Sjeff* DESCRIPTION 600219820Sjeff* This function posts a message to a Dispatcher object. 601219820Sjeff* 602219820Sjeff* SYNOPSIS 603219820Sjeff*/ 604219820Sjeffvoid 605219820Sjeffcl_disp_get_queue_status(IN const cl_disp_reg_handle_t handle, 606219820Sjeff OUT uint32_t * p_num_queued_msgs, 607219820Sjeff OUT uint64_t * p_last_msg_queue_time_ms); 608219820Sjeff/* 609219820Sjeff* PARAMETERS 610219820Sjeff* handle 611219820Sjeff* [in] cl_disp_reg_handle_t value return by cl_disp_register. 612219820Sjeff* 613219820Sjeff* p_last_msg_queue_time_ms 614219820Sjeff* [out] pointer to a variable to hold the time the last popped up message 615219820Sjeff* spent in the queue 616219820Sjeff* 617219820Sjeff* p_num_queued_msgs 618219820Sjeff* [out] number of messages in the queue 619219820Sjeff* 620219820Sjeff* RETURN VALUE 621219820Sjeff* Thr time the last popped up message stayed in the queue, in msec 622219820Sjeff* 623219820Sjeff* NOTES 624219820Sjeff* Extarnel Locking is not required. 625219820Sjeff* 626219820Sjeff* SEE ALSO 627219820Sjeff* Dispatcher 628219820Sjeff*********/ 629219820Sjeff 630219820SjeffEND_C_DECLS 631219820Sjeff#endif /* !defined(_CL_DISPATCHER_H_) */ 632