| 术语 | registerwaitforsingleobject |
| 释义 | RegisterWaitForSingleObject 语法： C++ BOOL WINAPI RegisterWaitForSingleObject( __out PHANDLE phNewWaitObject, __in HANDLE hObject, __in WAITORTIMERCALLBACK Callback, __in_opt PVOID Context, __in ULONG dwMilliseconds, __in ULONG dwFlags ); RegisterWaitForSingleObject功能 指示在等待线程池线程等待的对象。排队等待的线程指定的回调函数的线程池时，出现下列情况之一： 指定的对象是在信号状态。 在超时间隔经过的时间。 参数 phNewWaitObject [out] 一个变量，它接收等待处理返回的指针。请注意，等待处理，不能在函数中使用，需要一个对象处理诸如CloseHandle。 hObject [in] 句柄的对象。对于一个对象的句柄类型可以指定清单，请参阅下面的备注部分。 如果这个处理是封闭，而该等待仍悬而未决，该函数的行为是不确定的。 在处理必须有正确的同步访问。有关更多信息，请参阅标准访问权限。 回调 [in] 该申请的指针定义的类型的功能WAITORTIMERCALLBACK时要执行hObject是在信号状态，或dwMilliseconds的经过的。有关更多信息，请参阅WaitOrTimerCallback。 上下文[中，可选] 一个值传递给回调函数。 dwMilliseconds的 [in] 在超时间隔时间，以毫秒为单位。函数，如果经过的时间间隔，即使对象的状态是无信号的回报。如果dwMilliseconds的是零，函数测试对象的状态并立即返回。如果dwMilliseconds的是无限的，该函数的超时时间间隔从未经过的。 dwFlags [in] 此参数可以是一个或多个下列值。有关使用与该对象仍标志着这些值的信息，请参见备注部分。 ValueMeaning WT_EXECUTEDEFAULT 0x00000000By默认情况下，回调函数是排队到非I / O工作线程。 WT_EXECUTEINIOTHREAD 0x00000001The回调函数是排队一个I / O工作线程。此标志应使用的功能，如果要在一个线程，在一个可报警状态等待执行。 回调函数是作为的APC队列。一定要解决重入问题，如果该函数执行一个可报警等待操作。 WT_EXECUTEINPERSISTENTTHREAD 0x00000080The回调函数是一个线程排队从未终止。它不能保证在同一线程是每次使用。这个标志应该只用于短期任务，也可能影响到其他等业务。 请注意，目前没有工作线程是真正持久的，虽然没有工作线程将终止，如果有任何挂起的I / O请求。 WT_EXECUTEINWAITTHREAD 0x00000004The回调函数调用等待线程本身。这个标志应该只用于短期任务，也可能影响到其他等业务。 如果会发生死锁其他线程获得的排他锁，并调用UnregisterWait或UnregisterWaitEx功能，而在回调函数试图获得相同的锁。 WT_EXECUTELONGFUNCTION 0x00000010The回调函数可以执行一个漫长的等待。此标志帮助系统，以决定是否应该创建一个新线程。 WT_EXECUTEONLYONCE 0x00000008The线程将不再等待处理后的回调函数被调用一次。否则，定时器则每次等待操作完成，直到等待操作被取消。 WT_TRANSFER_IMPERSONATION 0x00000100Callback功能将使用当前的访问令牌，无论是过程或模拟令牌。如果此标志没有被指定，回调函数只执行进程令牌。 Windows XP/2000操作系统：这个标志是，直到Windows SP2和Windows Server 2003的XP的支持。 返回值 如果函数成功，返回值为非零。 如果函数失败，返回值是零。没有这个值可以通过调用GetLastError函数检索功能定义的错误。 备注 新的等待线程在需要时自动创建。等待的操作是由一个线程池中等待线程。回调例程执行的工作线程时，对象的状态变为信号或超时间隔经过的。如果dwFlags不是WT_EXECUTEONLYONCE，计时器每次复位信号或事件的时间间隔内经过的时间。 当等待完成后，您必须调用UnregisterWait或UnregisterWaitEx功能取消等待操作。 (即使使用WT_EXECUTEONLYONCE等待，必须取消。行动)不要让内部的回调函数要么这些功能阻塞调用。 请注意，您不应该脉冲的事件对象传递给RegisterWaitForSingleObject，因为等待线程可能无法检测到信号的事件之前，它被重置。您不应该注册一个剩下的暗示(如手动复位事件或终止的进程对象)，除非您设置WT_EXECUTEONLYONCE或WT_EXECUTEINWAITTHREAD标志。至于其他标志，回调函数可称为事件之前也多次被重置。 函数修改了某些类型的同步对象的状态。 Modification occurs only for the object whose signaled state caused the wait condition to be satisfied.例如，一个信号量对象计数减少1。 该RegisterWaitForSingleObject功能可以等待下列对象： 更改通知 控制台输入 事件 内存资源通知 互斥 工艺 信号量 线 可等待定时器 有关更多信息，请参阅同步对象。 默认情况下，线程池500最大线程。为了提高这个限制，使用WT_SET_MAX_THREADPOOL_THREAD宏定义在WINNT.H。 #define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \\ ((Flags)|=(Limit)<<16) 使用此宏时指定dwFlags参数。该宏的参数所需的旗帜和新的限制(最多(2“”16)-1线程)。但是，请注意您的应用程序可以提高保存的工作线程数量少的表现。 工作项和所有职能它呼吁必须是线程池安全。因此，您不能调用一个异步调用默认的回调环境，需要一个持久的线程，如RegNotifyChangeKeyValue功能。相反，设置线程池的最大等于最小线程池使用SetThreadpoolThreadMaximum和SetThreadpoolThreadMinimum功能，或创建自己的线程使用CreateThread函数。 (对于原来的线程池API，指定WT_EXECUTEINPERSISTENTTHREAD使用QueueUserWorkItem函数。) 要编译的应用程序使用此功能，定义_WIN32_WINNT为0x0500或更高版本。有关详细信息，请参阅使用Windows头。 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinbase.h(头文件：winuser.h) LibraryKernel32.lib DLLKernel32.dll 参见 同步功能 线程池 UnregisterWait UnregisterWaitEx 等待函数 WaitOrTimerCallback 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年8月27日 ＝＝英文原文＝＝RegisterWaitForSingleObject Function Directs a wait thread in the thread pool to wait on the object. The wait thread queues the specified callback function to the thread pool when one of the following occurs: The specified object is in the signaled state. The time-out interval elapses. Syntax C++ BOOL WINAPI RegisterWaitForSingleObject( __out PHANDLE phNewWaitObject, __in HANDLE hObject, __in WAITORTIMERCALLBACK Callback, __in_opt PVOID Context, __in ULONG dwMilliseconds, __in ULONG dwFlags ); Parameters phNewWaitObject [out] A pointer to a variable that receives a wait handle on return. Note that a wait handle cannot be used in functions that require an object handle, such as CloseHandle . hObject [in] A handle to the object. For a list of the object types whose handles can be specified, see the following Remarks section. If this handle is closed while the wait is still pending, the function's behavior is undefined. The handles must have the SYNCHRONIZE access right. For more information, see Standard Access Rights . Callback [in] A pointer to the application-defined function of type WAITORTIMERCALLBACK to be executed when hObject is in the signaled state, or dwMilliseconds elapses. For more information, see WaitOrTimerCallback . Context [in, optional] A single value that is passed to the callback function. dwMilliseconds [in] The time-out interval, in milliseconds. The function returns if the interval elapses, even if the object's state is nonsignaled. If dwMilliseconds is zero, the function tests the object's state and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses. dwFlags [in] This parameter can be one or more of the following values. For information about using these values with objects that remain signaled, see the Remarks section. ValueMeaning WT_EXECUTEDEFAULT 0x00000000By default, the callback function is queued to a non-I/O worker thread. WT_EXECUTEINIOTHREAD 0x00000001The callback function is queued to an I/O worker thread. This flag should be used if the function should be executed in a thread that waits in an alertable state. The callback function is queued as an APC. Be sure to address reentrancy issues if the function performs an alertable wait operation. WT_EXECUTEINPERSISTENTTHREAD 0x00000080The callback function is queued to a thread that never terminates. It does not guarantee that the same thread is used each time. This flag should be used only for short tasks or it could affect other wait operations. Note that currently no worker thread is truly persistent, although no worker thread will terminate if there are any pending I/O requests. WT_EXECUTEINWAITTHREAD 0x00000004The callback function is invoked by the wait thread itself. This flag should be used only for short tasks or it could affect other wait operations. Deadlocks can occur if some other thread acquires an exclusive lock and calls the UnregisterWait or UnregisterWaitEx function while the callback function is trying to acquire the same lock. WT_EXECUTELONGFUNCTION 0x00000010The callback function can perform a long wait. This flag helps the system to decide if it should create a new thread. WT_EXECUTEONLYONCE 0x00000008The thread will no longer wait on the handle after the callback function has been called once. Otherwise, the timer is reset every time the wait operation completes until the wait operation is canceled. WT_TRANSFER_IMPERSONATION 0x00000100Callback functions will use the current access token, whether it is a process or impersonation token. If this flag is not specified, callback functions execute only with the process token. Windows XP/2000: This flag is not supported until Windows XP with SP2 and Windows Server 2003. Return Value If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. There are no error values defined for this function that can be retrieved by calling GetLastError . Remarks New wait threads are created automatically when required. The wait operation is performed by a wait thread from the thread pool. The callback routine is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If dwFlags is not WT_EXECUTEONLYONCE, the timer is reset every time the event is signaled or the time-out interval elapses. When the wait is completed, you must call the UnregisterWait or UnregisterWaitEx function to cancel the wait operation. (Even wait operations that use WT_EXECUTEONLYONCE must be canceled.) Do not make a blocking call to either of these functions from within the callback function. Note that you should not pulse an event object passed to RegisterWaitForSingleObject, because the wait thread might not detect that the event is signaled before it is reset. You should not register an object that remains signaled (such as a manual reset event or terminated process) unless you set the WT_EXECUTEONLYONCE or WT_EXECUTEINWAITTHREAD flag. For other flags, the callback function might be called too many times before the event is reset. The function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore object is decreased by one. The RegisterWaitForSingleObject function can wait for the following objects: Change notification Console input Event Memory resource notification Mutex Process Semaphore Thread Waitable timer For more information, see Synchronization Objects . By default, the thread pool has a maximum of 500 threads. To raise this limit, use the WT_SET_MAX_THREADPOOL_THREAD macro defined in Winnt.h. #define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \\ ((Flags)|=(Limit)<<16) Use this macro when specifying the dwFlags parameter. The macro parameters are the desired flags and the new limit (up to (2<<16)-1 threads). However, note that your application can improve its performance by keeping the number of worker threads low. The work item and all functions it calls must be thread-pool safe. Therefore, you cannot call an asynchronous call that requires a persistent thread, such as the RegNotifyChangeKeyValue function, from the default callback environment. Instead, set the thread pool maximum equal to the thread pool minimum using the SetThreadpoolThreadMaximum and SetThreadpoolThreadMinimum functions, or create your own thread using the CreateThread function. (For the original thread pool API, specify WT_EXECUTEINPERSISTENTTHREAD using the QueueUserWorkItem function.) To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers . Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderWinbase.h (include Windows.h) LibraryKernel32.lib DLLKernel32.dll See Also Synchronization Functions Thread Pooling UnregisterWait UnregisterWaitEx Wait Functions WaitOrTimerCallback Send comments about this topic to Microsoft Build date: 8/27/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/ms685061(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。