1
0

Interfaces.cs 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515
  1. using System;
  2. using System.Threading;
  3. namespace Amib.Threading
  4. {
  5. #region Delegates
  6. /// <summary>
  7. /// A delegate that represents the method to run as the work item
  8. /// </summary>
  9. /// <param name="state">A state object for the method to run</param>
  10. public delegate object WorkItemCallback(object state);
  11. /// <summary>
  12. /// A delegate to call after the WorkItemCallback completed
  13. /// </summary>
  14. /// <param name="wir">The work item result object</param>
  15. public delegate void PostExecuteWorkItemCallback(IWorkItemResult wir);
  16. /// <summary>
  17. /// A delegate to call after the WorkItemCallback completed
  18. /// </summary>
  19. /// <param name="wir">The work item result object</param>
  20. public delegate void PostExecuteWorkItemCallback<TResult>(IWorkItemResult<TResult> wir);
  21. /// <summary>
  22. /// A delegate to call when a WorkItemsGroup becomes idle
  23. /// </summary>
  24. /// <param name="workItemsGroup">A reference to the WorkItemsGroup that became idle</param>
  25. public delegate void WorkItemsGroupIdleHandler(IWorkItemsGroup workItemsGroup);
  26. /// <summary>
  27. /// A delegate to call after a thread is created, but before
  28. /// it's first use.
  29. /// </summary>
  30. public delegate void ThreadInitializationHandler();
  31. /// <summary>
  32. /// A delegate to call when a thread is about to exit, after
  33. /// it is no longer belong to the pool.
  34. /// </summary>
  35. public delegate void ThreadTerminationHandler();
  36. #endregion
  37. #region IWorkItemsGroup interface
  38. /// <summary>
  39. /// IWorkItemsGroup interface
  40. /// Created by SmartThreadPool.CreateWorkItemsGroup()
  41. /// </summary>
  42. public interface IWorkItemsGroup
  43. {
  44. /// <summary>
  45. /// Get/Set the name of the WorkItemsGroup
  46. /// </summary>
  47. string Name { get; set; }
  48. /// <summary>
  49. /// Get/Set the maximum number of workitem that execute cocurrency on the thread pool
  50. /// </summary>
  51. int Concurrency { get; set; }
  52. /// <summary>
  53. /// Get the number of work items waiting in the queue.
  54. /// </summary>
  55. int WaitingCallbacks { get; }
  56. /// <summary>
  57. /// Get an array with all the state objects of the currently running items.
  58. /// The array represents a snap shot and impact performance.
  59. /// </summary>
  60. object[] GetStates();
  61. /// <summary>
  62. /// Get the WorkItemsGroup start information
  63. /// </summary>
  64. WIGStartInfo WIGStartInfo { get; }
  65. /// <summary>
  66. /// Starts to execute work items
  67. /// </summary>
  68. void Start();
  69. /// <summary>
  70. /// Cancel all the work items.
  71. /// Same as Cancel(false)
  72. /// </summary>
  73. void Cancel();
  74. /// <summary>
  75. /// Cancel all work items using thread abortion
  76. /// </summary>
  77. /// <param name="abortExecution">True to stop work items by raising ThreadAbortException</param>
  78. void Cancel(bool abortExecution);
  79. /// <summary>
  80. /// Wait for all work item to complete.
  81. /// </summary>
  82. void WaitForIdle();
  83. /// <summary>
  84. /// Wait for all work item to complete, until timeout expired
  85. /// </summary>
  86. /// <param name="timeout">How long to wait for the work items to complete</param>
  87. /// <returns>Returns true if work items completed within the timeout, otherwise false.</returns>
  88. bool WaitForIdle(TimeSpan timeout);
  89. /// <summary>
  90. /// Wait for all work item to complete, until timeout expired
  91. /// </summary>
  92. /// <param name="millisecondsTimeout">How long to wait for the work items to complete in milliseconds</param>
  93. /// <returns>Returns true if work items completed within the timeout, otherwise false.</returns>
  94. bool WaitForIdle(int millisecondsTimeout);
  95. /// <summary>
  96. /// IsIdle is true when there are no work items running or queued.
  97. /// </summary>
  98. bool IsIdle { get; }
  99. /// <summary>
  100. /// This event is fired when all work items are completed.
  101. /// (When IsIdle changes to true)
  102. /// This event only work on WorkItemsGroup. On SmartThreadPool
  103. /// it throws the NotImplementedException.
  104. /// </summary>
  105. event WorkItemsGroupIdleHandler OnIdle;
  106. #region QueueWorkItem
  107. IWorkItemResult QueueWorkItem(WaitCallback callback);
  108. IWorkItemResult QueueWorkItem(WaitCallback callback, object state);
  109. IWorkItemResult QueueWorkItem(WorkItemInfo workItemInfo, WaitCallback callback);
  110. IWorkItemResult QueueWorkItem(WorkItemInfo workItemInfo, WaitCallback callback, object state);
  111. /// <summary>
  112. /// Queue a work item
  113. /// </summary>
  114. /// <param name="callback">A callback to execute</param>
  115. /// <returns>Returns a work item result</returns>
  116. IWorkItemResult QueueWorkItem(WorkItemCallback callback);
  117. /// <summary>
  118. /// Queue a work item
  119. /// </summary>
  120. /// <param name="callback">A callback to execute</param>
  121. /// <param name="state">
  122. /// The context object of the work item. Used for passing arguments to the work item.
  123. /// </param>
  124. /// <returns>Returns a work item result</returns>
  125. IWorkItemResult QueueWorkItem(WorkItemCallback callback, object state);
  126. /// <summary>
  127. /// Queue a work item
  128. /// </summary>
  129. /// <param name="callback">A callback to execute</param>
  130. /// <param name="state">
  131. /// The context object of the work item. Used for passing arguments to the work item.
  132. /// </param>
  133. /// <param name="postExecuteWorkItemCallback">
  134. /// A delegate to call after the callback completion
  135. /// </param>
  136. /// <returns>Returns a work item result</returns>
  137. IWorkItemResult QueueWorkItem(WorkItemCallback callback, object state, PostExecuteWorkItemCallback postExecuteWorkItemCallback);
  138. /// <summary>
  139. /// Queue a work item
  140. /// </summary>
  141. /// <param name="callback">A callback to execute</param>
  142. /// <param name="state">
  143. /// The context object of the work item. Used for passing arguments to the work item.
  144. /// </param>
  145. /// <param name="postExecuteWorkItemCallback">
  146. /// A delegate to call after the callback completion
  147. /// </param>
  148. /// <param name="callToPostExecute">Indicates on which cases to call to the post execute callback</param>
  149. /// <returns>Returns a work item result</returns>
  150. IWorkItemResult QueueWorkItem(WorkItemCallback callback, object state, PostExecuteWorkItemCallback postExecuteWorkItemCallback, CallToPostExecute callToPostExecute);
  151. /// <summary>
  152. /// Queue a work item
  153. /// </summary>
  154. /// <param name="workItemInfo">Work item info</param>
  155. /// <param name="callback">A callback to execute</param>
  156. /// <returns>Returns a work item result</returns>
  157. IWorkItemResult QueueWorkItem(WorkItemInfo workItemInfo, WorkItemCallback callback);
  158. /// <summary>
  159. /// Queue a work item
  160. /// </summary>
  161. /// <param name="workItemInfo">Work item information</param>
  162. /// <param name="callback">A callback to execute</param>
  163. /// <param name="state">
  164. /// The context object of the work item. Used for passing arguments to the work item.
  165. /// </param>
  166. /// <returns>Returns a work item result</returns>
  167. IWorkItemResult QueueWorkItem(WorkItemInfo workItemInfo, WorkItemCallback callback, object state);
  168. #endregion
  169. #region QueueWorkItem(Action<...>)
  170. /// <summary>
  171. /// Queue a work item.
  172. /// </summary>
  173. /// <returns>Returns a IWorkItemResult object, but its GetResult() will always return null</returns>
  174. IWorkItemResult QueueWorkItem(Action action);
  175. /// <summary>
  176. /// Queue a work item.
  177. /// </summary>
  178. /// <returns>Returns a IWorkItemResult object, but its GetResult() will always return null</returns>
  179. IWorkItemResult QueueWorkItem<T>(Action<T> action, T arg);
  180. /// <summary>
  181. /// Queue a work item.
  182. /// </summary>
  183. /// <returns>Returns a IWorkItemResult object, but its GetResult() will always return null</returns>
  184. IWorkItemResult QueueWorkItem<T1, T2>(Action<T1, T2> action, T1 arg1, T2 arg2);
  185. /// <summary>
  186. /// Queue a work item.
  187. /// </summary>
  188. /// <returns>Returns a IWorkItemResult object, but its GetResult() will always return null</returns>
  189. IWorkItemResult QueueWorkItem<T1, T2, T3>(Action<T1, T2, T3> action, T1 arg1, T2 arg2, T3 arg3);
  190. /// <summary>
  191. /// Queue a work item.
  192. /// </summary>
  193. /// <returns>Returns a IWorkItemResult object, but its GetResult() will always return null</returns>
  194. IWorkItemResult QueueWorkItem<T1, T2, T3, T4>(Action<T1, T2, T3, T4> action, T1 arg1, T2 arg2, T3 arg3, T4 arg4);
  195. #endregion
  196. #region QueueWorkItem(Func<...>)
  197. /// <summary>
  198. /// Queue a work item.
  199. /// </summary>
  200. /// <returns>Returns a IWorkItemResult&lt;TResult&gt; object.
  201. /// its GetResult() returns a TResult object</returns>
  202. IWorkItemResult<TResult> QueueWorkItem<TResult>(Func<TResult> func);
  203. /// <summary>
  204. /// Queue a work item.
  205. /// </summary>
  206. /// <returns>Returns a IWorkItemResult&lt;TResult&gt; object.
  207. /// its GetResult() returns a TResult object</returns>
  208. IWorkItemResult<TResult> QueueWorkItem<T, TResult>(Func<T, TResult> func, T arg);
  209. /// <summary>
  210. /// Queue a work item.
  211. /// </summary>
  212. /// <returns>Returns a IWorkItemResult&lt;TResult&gt; object.
  213. /// its GetResult() returns a TResult object</returns>
  214. IWorkItemResult<TResult> QueueWorkItem<T1, T2, TResult>(Func<T1, T2, TResult> func, T1 arg1, T2 arg2);
  215. /// <summary>
  216. /// Queue a work item.
  217. /// </summary>
  218. /// <returns>Returns a IWorkItemResult&lt;TResult&gt; object.
  219. /// its GetResult() returns a TResult object</returns>
  220. IWorkItemResult<TResult> QueueWorkItem<T1, T2, T3, TResult>(Func<T1, T2, T3, TResult> func, T1 arg1, T2 arg2, T3 arg3);
  221. /// <summary>
  222. /// Queue a work item.
  223. /// </summary>
  224. /// <returns>Returns a IWorkItemResult&lt;TResult&gt; object.
  225. /// its GetResult() returns a TResult object</returns>
  226. IWorkItemResult<TResult> QueueWorkItem<T1, T2, T3, T4, TResult>(Func<T1, T2, T3, T4, TResult> func, T1 arg1, T2 arg2, T3 arg3, T4 arg4);
  227. #endregion
  228. }
  229. #endregion
  230. #region CallToPostExecute enumerator
  231. [Flags]
  232. public enum CallToPostExecute
  233. {
  234. /// <summary>
  235. /// Never call to the PostExecute call back
  236. /// </summary>
  237. Never = 0x00,
  238. /// <summary>
  239. /// Call to the PostExecute only when the work item is cancelled
  240. /// </summary>
  241. WhenWorkItemCanceled = 0x01,
  242. /// <summary>
  243. /// Call to the PostExecute only when the work item is not cancelled
  244. /// </summary>
  245. WhenWorkItemNotCanceled = 0x02,
  246. /// <summary>
  247. /// Always call to the PostExecute
  248. /// </summary>
  249. Always = WhenWorkItemCanceled | WhenWorkItemNotCanceled,
  250. }
  251. #endregion
  252. #region IWorkItemResult interface
  253. /// <summary>
  254. /// The common interface of IWorkItemResult and IWorkItemResult&lt;T&gt;
  255. /// </summary>
  256. public interface IWaitableResult
  257. {
  258. /// <summary>
  259. /// This method intent is for internal use.
  260. /// </summary>
  261. /// <returns></returns>
  262. IWorkItemResult GetWorkItemResult();
  263. /// <summary>
  264. /// This method intent is for internal use.
  265. /// </summary>
  266. /// <returns></returns>
  267. IWorkItemResult<TResult> GetWorkItemResultT<TResult>();
  268. }
  269. /// <summary>
  270. /// IWorkItemResult interface.
  271. /// Created when a WorkItemCallback work item is queued.
  272. /// </summary>
  273. public interface IWorkItemResult : IWorkItemResult<object>
  274. {
  275. }
  276. /// <summary>
  277. /// IWorkItemResult&lt;TResult&gt; interface.
  278. /// Created when a Func&lt;TResult&gt; work item is queued.
  279. /// </summary>
  280. public interface IWorkItemResult<TResult> : IWaitableResult
  281. {
  282. /// <summary>
  283. /// Get the result of the work item.
  284. /// If the work item didn't run yet then the caller waits.
  285. /// </summary>
  286. /// <returns>The result of the work item</returns>
  287. TResult GetResult();
  288. /// <summary>
  289. /// Get the result of the work item.
  290. /// If the work item didn't run yet then the caller waits until timeout.
  291. /// </summary>
  292. /// <returns>The result of the work item</returns>
  293. /// On timeout throws WorkItemTimeoutException
  294. TResult GetResult(
  295. int millisecondsTimeout,
  296. bool exitContext);
  297. /// <summary>
  298. /// Get the result of the work item.
  299. /// If the work item didn't run yet then the caller waits until timeout.
  300. /// </summary>
  301. /// <returns>The result of the work item</returns>
  302. /// On timeout throws WorkItemTimeoutException
  303. TResult GetResult(
  304. TimeSpan timeout,
  305. bool exitContext);
  306. /// <summary>
  307. /// Get the result of the work item.
  308. /// If the work item didn't run yet then the caller waits until timeout or until the cancelWaitHandle is signaled.
  309. /// </summary>
  310. /// <param name="millisecondsTimeout">Timeout in milliseconds, or -1 for infinite</param>
  311. /// <param name="exitContext">
  312. /// true to exit the synchronization domain for the context before the wait (if in a synchronized context), and reacquire it; otherwise, false.
  313. /// </param>
  314. /// <param name="cancelWaitHandle">A cancel wait handle to interrupt the blocking if needed</param>
  315. /// <returns>The result of the work item</returns>
  316. /// On timeout throws WorkItemTimeoutException
  317. /// On cancel throws WorkItemCancelException
  318. TResult GetResult(
  319. int millisecondsTimeout,
  320. bool exitContext,
  321. WaitHandle cancelWaitHandle);
  322. /// <summary>
  323. /// Get the result of the work item.
  324. /// If the work item didn't run yet then the caller waits until timeout or until the cancelWaitHandle is signaled.
  325. /// </summary>
  326. /// <returns>The result of the work item</returns>
  327. /// On timeout throws WorkItemTimeoutException
  328. /// On cancel throws WorkItemCancelException
  329. TResult GetResult(
  330. TimeSpan timeout,
  331. bool exitContext,
  332. WaitHandle cancelWaitHandle);
  333. /// <summary>
  334. /// Get the result of the work item.
  335. /// If the work item didn't run yet then the caller waits.
  336. /// </summary>
  337. /// <param name="e">Filled with the exception if one was thrown</param>
  338. /// <returns>The result of the work item</returns>
  339. TResult GetResult(out Exception e);
  340. /// <summary>
  341. /// Get the result of the work item.
  342. /// If the work item didn't run yet then the caller waits until timeout.
  343. /// </summary>
  344. /// <param name="millisecondsTimeout"></param>
  345. /// <param name="exitContext"></param>
  346. /// <param name="e">Filled with the exception if one was thrown</param>
  347. /// <returns>The result of the work item</returns>
  348. /// On timeout throws WorkItemTimeoutException
  349. TResult GetResult(
  350. int millisecondsTimeout,
  351. bool exitContext,
  352. out Exception e);
  353. /// <summary>
  354. /// Get the result of the work item.
  355. /// If the work item didn't run yet then the caller waits until timeout.
  356. /// </summary>
  357. /// <param name="exitContext"></param>
  358. /// <param name="e">Filled with the exception if one was thrown</param>
  359. /// <param name="timeout"></param>
  360. /// <returns>The result of the work item</returns>
  361. /// On timeout throws WorkItemTimeoutException
  362. TResult GetResult(
  363. TimeSpan timeout,
  364. bool exitContext,
  365. out Exception e);
  366. /// <summary>
  367. /// Get the result of the work item.
  368. /// If the work item didn't run yet then the caller waits until timeout or until the cancelWaitHandle is signaled.
  369. /// </summary>
  370. /// <param name="millisecondsTimeout">Timeout in milliseconds, or -1 for infinite</param>
  371. /// <param name="exitContext">
  372. /// true to exit the synchronization domain for the context before the wait (if in a synchronized context), and reacquire it; otherwise, false.
  373. /// </param>
  374. /// <param name="cancelWaitHandle">A cancel wait handle to interrupt the blocking if needed</param>
  375. /// <param name="e">Filled with the exception if one was thrown</param>
  376. /// <returns>The result of the work item</returns>
  377. /// On timeout throws WorkItemTimeoutException
  378. /// On cancel throws WorkItemCancelException
  379. TResult GetResult(
  380. int millisecondsTimeout,
  381. bool exitContext,
  382. WaitHandle cancelWaitHandle,
  383. out Exception e);
  384. /// <summary>
  385. /// Get the result of the work item.
  386. /// If the work item didn't run yet then the caller waits until timeout or until the cancelWaitHandle is signaled.
  387. /// </summary>
  388. /// <returns>The result of the work item</returns>
  389. /// <param name="cancelWaitHandle"></param>
  390. /// <param name="e">Filled with the exception if one was thrown</param>
  391. /// <param name="timeout"></param>
  392. /// <param name="exitContext"></param>
  393. /// On timeout throws WorkItemTimeoutException
  394. /// On cancel throws WorkItemCancelException
  395. TResult GetResult(
  396. TimeSpan timeout,
  397. bool exitContext,
  398. WaitHandle cancelWaitHandle,
  399. out Exception e);
  400. /// <summary>
  401. /// Gets an indication whether the asynchronous operation has completed.
  402. /// </summary>
  403. bool IsCompleted { get; }
  404. /// <summary>
  405. /// Gets an indication whether the asynchronous operation has been canceled.
  406. /// </summary>
  407. bool IsCanceled { get; }
  408. /// <summary>
  409. /// Gets the user-defined object that contains context data
  410. /// for the work item method.
  411. /// </summary>
  412. object State { get; }
  413. /// <summary>
  414. /// Same as Cancel(false).
  415. /// </summary>
  416. bool Cancel();
  417. /// <summary>
  418. /// Cancel the work item execution.
  419. /// If the work item is in the queue then it won't execute
  420. /// If the work item is completed, it will remain completed
  421. /// If the work item is in progress then the user can check the SmartThreadPool.IsWorkItemCanceled
  422. /// property to check if the work item has been cancelled. If the abortExecution is set to true then
  423. /// the Smart Thread Pool will send an AbortException to the running thread to stop the execution
  424. /// of the work item. When an in progress work item is canceled its GetResult will throw WorkItemCancelException.
  425. /// If the work item is already cancelled it will remain cancelled
  426. /// </summary>
  427. /// <param name="abortExecution">When true send an AbortException to the executing thread.</param>
  428. /// <returns>Returns true if the work item was not completed, otherwise false.</returns>
  429. bool Cancel(bool abortExecution);
  430. /// <summary>
  431. /// Return the result, same as GetResult()
  432. /// </summary>
  433. TResult Result { get; }
  434. /// <summary>
  435. /// Returns the exception if occured otherwise returns null.
  436. /// </summary>
  437. object Exception { get; }
  438. }
  439. #endregion
  440. }