ReactOS 0.4.15-dev-8145-ga541a46
fxworkitem.hpp
Go to the documentation of this file.
1/*++
2
3Copyright (c) Microsoft Corporation
4
5Module Name:
6
7 FxWorkItem.hpp
8
9Abstract:
10
11 This module implements a frameworks managed WorkItem that
12 can synchrononize with driver frameworks object locks.
13
14Author:
15
16
17
18
19Environment:
20
21 Both kernel and user mode
22
23Revision History:
24
25
26--*/
27
28#ifndef _FXWORKITEM_H_
29#define _FXWORKITEM_H_
30
31//
32// Driver Frameworks WorkItem Design:
33//
34// The driver frameworks provides an optional WorkItem wrapper object that allows
35// a reference counted WorkItem object to be created that can synchronize
36// automatically with certain frameworks objects.
37//
38// This provides automatic synchronization between the WorkItems execution, and the
39// frameworks objects event callbacks into the device driver.
40//
41// The WDFWORKITEM object is designed to be re-useable, in which it can be re-linked
42// into the WorkItem queue after firing.
43//
44// Calling GetWorkItemPtr returns the WDM IoWorkItem.
45//
46
48
49private:
50 //
51 // WDM work item.
52 //
54
55 // Ensures only one of either Delete or Cleanup runsdown the object
57
58 //
59 // If this is set, a WorkItem has been enqueued
60 //
62
63 //
64 // This count is used to prevent the object from being deleted if
65 // one worker thread is preempted right after we drop the lock to call
66 // the client callback and another workitem gets queued and runs
67 // to completion and signals the event.
68 //
70
71 //
72 // This is the Framework object who is associated with the work
73 // item if supplied
74 //
76
77 //
78 // This is the callback lock for the object this WorkItem will
79 // synchronize with
80 //
82
83 //
84 // This is the object whose reference count actually controls
85 // the lifetime of the m_CallbackLock
86 //
88
89 //
90 // This is the user supplied callback function and context
91 //
93
94 //
95 // This event is signaled when the workitem is done processing
96 // an Enqueue request.
97 //
99
100 //
101 // This is a pointer to thread object that invoked our workitem
102 // callback. This value will be used to avoid deadlock when we try
103 // to flush the workitem.
104 //
106
107public:
108
109 static
112 _Create(
113 __in PFX_DRIVER_GLOBALS FxDriverGlobals,
116 __in FxObject* ParentObject,
117 __out WDFWORKITEM* WorkItem
118 );
119
120/*++
121
122Routine Description:
123
124 Construct an FxWorkItem
125
126Arguments:
127
128Returns:
129
130 NTSTATUS
131
132--*/
133
135 __in PFX_DRIVER_GLOBALS FxDriverGlobals
136 );
137
138 virtual
140 );
141
144 return m_WorkItem.GetWorkItem();
145 }
146
147/*++
148
149Routine Description:
150
151 Initialize the WorkItem using either the caller supplied WorkItem
152 struct, or if NULL, our own internally allocated one
153
154Arguments:
155
156Returns:
157
158 NTSTATUS
159
160--*/
166 __in FxObject* ParentObject,
167 __out WDFWORKITEM* WorkItem
168 );
169
170 virtual
171 BOOLEAN
172 Dispose(
173 VOID
174 );
175
176 VOID
177 Enqueue(
178 );
179
182 )
183 {
184 if( m_Object != NULL ) {
185 return m_Object->GetObjectHandle();
186 }
187 else {
188 return NULL;
189 }
190 }
191
192 WDFWORKITEM
194 VOID
195 )
196 {
197 return (WDFWORKITEM) GetObjectHandle();
198 }
199
200private:
201
202 //
203 // Called from Dispose, or cleanup list to perform final flushing of any
204 // outstanding DPC's and dereferencing of objects.
205 //
206 VOID
208 );
209
210 VOID
212 );
213
214 static
217
218 VOID
220 VOID
221 );
222
223public:
224 VOID
226 VOID
227 );
228};
229
230#endif // _FXWORKITEM_H_
231
unsigned char BOOLEAN
LONG NTSTATUS
Definition: precomp.h:26
PVOID __inline GetObjectHandle(VOID)
Definition: fxobject.hpp:603
MdWorkItem GetWorkItemPtr()
Definition: fxworkitem.hpp:143
virtual ~FxWorkItem()
Definition: fxworkitem.cpp:68
FxCREvent m_WorkItemCompleted
Definition: fxworkitem.hpp:98
VOID Enqueue()
Definition: fxworkitem.cpp:288
WDFOBJECT GetAssociatedObject()
Definition: fxworkitem.hpp:181
FxObject * m_Object
Definition: fxworkitem.hpp:75
VOID WorkItemHandler()
Definition: fxworkitem.cpp:338
FxCallbackLock * m_CallbackLock
Definition: fxworkitem.hpp:81
BOOLEAN m_RunningDown
Definition: fxworkitem.hpp:56
ULONG m_WorkItemRunningCount
Definition: fxworkitem.hpp:69
static MX_WORKITEM_ROUTINE WorkItemThunk
Definition: fxworkitem.hpp:216
MxThread m_WorkItemThread
Definition: fxworkitem.hpp:105
FxObject * m_CallbackLockObject
Definition: fxworkitem.hpp:87
VOID FlushAndRundown()
Definition: fxworkitem.cpp:448
VOID WaitForSignal(VOID)
Definition: fxworkitem.cpp:534
PFN_WDF_WORKITEM m_Callback
Definition: fxworkitem.hpp:92
virtual BOOLEAN Dispose(VOID)
Definition: fxworkitem.cpp:479
BOOLEAN m_Enqueued
Definition: fxworkitem.hpp:61
static _Must_inspect_result_ NTSTATUS _Create(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_WORKITEM_CONFIG Config, __in PWDF_OBJECT_ATTRIBUTES Attributes, __in FxObject *ParentObject, __out WDFWORKITEM *WorkItem)
Definition: fxworkitem.cpp:109
MxWorkItem m_WorkItem
Definition: fxworkitem.hpp:53
WDFWORKITEM GetHandle(VOID)
Definition: fxworkitem.hpp:193
__inline MdWorkItem GetWorkItem()
Definition: mxworkitemkm.h:73
#define __in
Definition: dbghelp.h:35
#define __out
Definition: dbghelp.h:62
#define NULL
Definition: types.h:112
return pObject GetObjectHandle()
pFxWorkItem FlushAndWait()
#define _Must_inspect_result_
Definition: ms_sal.h:558
IO_WORKITEM_ROUTINE MX_WORKITEM_ROUTINE
Definition: mxworkitemkm.h:26
uint32_t ULONG
Definition: typedefs.h:59
_Must_inspect_result_ _In_ WDFDEVICE _In_ PWDF_CHILD_LIST_CONFIG Config
Definition: wdfchildlist.h:476
_Must_inspect_result_ _In_ WDFDMAENABLER _In_ _In_opt_ PWDF_OBJECT_ATTRIBUTES Attributes
_Must_inspect_result_ _In_ PWDF_WORKITEM_CONFIG _In_ PWDF_OBJECT_ATTRIBUTES _Out_ WDFWORKITEM * WorkItem
Definition: wdfworkitem.h:115
EVT_WDF_WORKITEM * PFN_WDF_WORKITEM
Definition: wdfworkitem.h:64
static void Initialize()
Definition: xlate.c:212