http://github.com/xbmc/xbmc
C++ Header | 101 lines | 0 code | 0 blank | 101 comment | 0 complexity | d468e0006054987b449d958b22dc97b1 MD5 | raw file
  1/**
2
3\page doc_adv_timeout Timeout long running scripts
4
5To prevent long running scripts to freeze the application it may be necessary
6to add a way to timeout the execution. This article presents two different
7ways to do so.
8
9\section doc_adv_timeout_1 With the line callback
10
11The line callback feature can be used to perform some special treatment
12during execution of the scripts. The callback is called for every script
13statement, which for example makes it possible to verify if the script has
14executed for too long time and if so suspend the execution to be resumed at
15a later time.
16
17Before calling the context's \ref asIScriptContext::Execute "Execute" method,
18set the callback function like so:
19
20\code
21int ExecuteScriptWithTimeOut(asIScriptContext *ctx)
22{
23  // Define the timeout as 1 second
24  DWORD timeOut = timeGetTime() + 1000;
25
26  // Set up the line callback that will timout the script
27  ctx->SetLineCallback(asFUNCTION(LineCallback), &timeOut, asCALL_CDECL);
28
29  // Execute the script
30  int status = ctx->Execute();
31
32  // If the status is asEXECUTION_SUSPENDED the script can
33  // be resumed by calling this function again.
34  return status;
35}
36
37// The line callback function is called by the VM for each statement that is executed
38void LineCallback(asIScriptContext *ctx, DWORD *timeOut)
39{
40  // If the time out is reached we suspend the script
41  if( *timeOut < timeGetTime() )
42    ctx->Suspend();
43}
44\endcode
45
46Take a look at the sample \ref doc_samples_events to
47see this working.
48
50
51A second thread can be set up to suspend the execution after the timeout. This thread
52can then be put to sleep so that it doesn't impact performance during the execution.
53When the thread wakes up it should call the context's \ref asIScriptContext::Suspend "Suspend" method.
54
55The below shows some possible code for doing this. Note that the code for setting up
56the thread is fictive, as this is different for each target OS.
57
58\code
59// The variables that are shared between the threads
62
63// This function will be executed in the secondary thread
65{
66  // Put the thread to sleep until the timeout (1 second)
67  Sleep(1000);
68
69  // When we wake-up we call the context's Suspend method
70  ctx->Suspend();
71}
72
73// This function sets up the timeout thread and executes the script
74int ExecuteScriptWithTimeOut(asIScriptContext *ctx)
75{
76  // Set the shared context pointer before creating the thread
77  threadCtx = ctx;
78
79  // Create the thread that will immediately go to sleep
81
82  // Execute the script
83  int status = ctx->Execute();
84
85  // Destroy the secondary thread before releasing the context
87
88  // Clear the global variables
89  threadId = 0;
90  threadCtx = 0;
91
92  // If the status is asEXECUTION_SUSPENDED the script can
93  // be resumed by calling this function again.
94
95  return status;
96}
97\endcode
98
99Observe that this way of doing it is safe even if the AngelScript library has been