Skip to content

Commit e8a0373

Browse files
AbelChengAbelCheng
authored
Add LICENSE and docs exported from CodePlex
1 parent 7626be9 commit e8a0373

File tree

6 files changed

+219
-0
lines changed

6 files changed

+219
-0
lines changed

‎docs/Home.html‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
<div class="wikidoc">
2+
<p><strong>Project Description</strong><br>
3+
The dbParallel is a Database Task Parallel Foundation that provides database developers an application level support for parallel programming. Being distinct from Oracle 11g R2's DBMS_PARALLEL_EXECUTE parallelism within a query by chunks, dbParallel works more
4+
like a .NET Task Parallel Library implemented on database side, it handles the partitioning of the asynchronous job, the scheduling of tasks, state management, and other low-level details in a lightweight implementation.</p>
5+
<div><strong>Get started</strong><br>
6+
A quick example (for Oracle Version)</div>
7+
<div style="color:black; background-color:white">
8+
<pre><span style="color:blue">PROCEDURE</span> TEST_1
9+
<span style="color:blue">AS</span>
10+
tPJob_ID PLS_INTEGER;
11+
tSQL VARCHAR2(256);
12+
<span style="color:blue">BEGIN</span>
13+
tPJob_ID := <span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>CREATE_PJOB(<span style="color:#a31515">'App1'</span>, <span style="color:#a31515">'User1'</span>, <span style="color:#a31515">'This is test1.'</span>);
14+
15+
tSQL := UTL_LMS.FORMAT_MESSAGE(<span style="color:#a31515">'DBMS_LOCK.SLEEP(%d)'</span>, 10);
16+
<span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_TASK(tPJob_ID, tSQL, 60, <span style="color:#a31515">'Task1 sleep for 10 seconds.'</span>);
17+
18+
tSQL := UTL_LMS.FORMAT_MESSAGE(<span style="color:#a31515">'DBMS_LOCK.SLEEP(%d)'</span>, 70);
19+
<span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_TASK(tPJob_ID, tSQL, 60, <span style="color:#a31515">'Task2 sleep for 70 seconds.'</span>);
20+
21+
tSQL := UTL_LMS.FORMAT_MESSAGE(<span style="color:#a31515">'DBMS_LOCK.SLEEP(%d)'</span>, 30);
22+
<span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_TASK(tPJob_ID, tSQL, 60, <span style="color:#a31515">'Task3 sleep for 30 seconds.'</span>);
23+
24+
tSQL := UTL_LMS.FORMAT_MESSAGE(<span style="color:#a31515">'DBMS_LOCK.SLEEP(%d)'</span>, 70);
25+
<span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_TASK(tPJob_ID, tSQL, 120, <span style="color:#a31515">'Task4 sleep for 70 seconds.'</span>);
26+
27+
tSQL := UTL_LMS.FORMAT_MESSAGE(<span style="color:#a31515">'DBMS_LOCK.SLEEP(%d)'</span>, 15);
28+
<span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_CALLBACK_FOR_SUCCESS(tPJob_ID, tSQL, 180, <span style="color:#a31515">'Sleep for 15s if all success.'</span>);
29+
30+
tSQL := UTL_LMS.FORMAT_MESSAGE(<span style="color:#a31515">'DBMS_LOCK.SLEEP(%d)'</span>, 25);
31+
<span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_CALLBACK_FOR_FAIL(tPJob_ID, tSQL, 180, <span style="color:#a31515">'Sleep for 25s if fail.'</span>);
32+
33+
<span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>START_PJOB(tPJob_ID);
34+
35+
DBMS_OUTPUT.PUT_LINE(<span style="color:#a31515">'New PJob_ID#'</span> || tPJob_ID);
36+
<span style="color:blue">END</span> TEST_1;</pre>
37+
</div>
38+
<div>The example executes Task1-4 in parallel and when everything is finished, the callback task is executed
39+
<em>(in this case callback will be a fail since task 2 failed - timeout)</em>.<br>
40+
<img src="http://download-codeplex.sec.s-msft.com/Download?ProjectName=dbparallel&DownloadId=370939" alt="" width="635" height="230" style="vertical-align:middle"></div>
41+
<p>&nbsp;</p>
42+
<p><strong>Features</strong><br>
43+
Following API list of current version reflects the features:</p>
44+
<ol>
45+
<li><span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>CREATE_PJOB<br>
46+
Each of the above sample processing units are called a PJob. PJob represents an asynchronous operation. This method returns a pJob Id for below methods (2, 3, 4, 5, 6).
47+
</li><li><span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_TASK<br>
48+
Each pJob contains one or more parallel tasks. Each task is a dynamic SQL. Call the ADD_TASK multiple times to add every parallel tasks into the pJob.
49+
</li><li><span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_CALLBACK_FOR_SUCCESS<br>
50+
This is a optional method. Since a pJob is asynchronous, the callback Task is called to execute a continuation when all the parallel Tasks successfully completed.
51+
</li><li><span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>ADD_CALLBACK_FOR_FAIL<br>
52+
This is a optional method. Similar but opposite to previous callback for success, the callback Task for fail is called to execute a continuation when all the parallel Tasks completed but any of them throw out database exception(s).
53+
</li><li><span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>START_PJOB<br>
54+
Starts the pJob, scheduling it for execution. </li><li><span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>TRY_CANCEL_PJOB<br>
55+
Try to cancel a scheduled pJob if it hasn't begin to execute. </li><li><span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>START_NEW_SINGLE_TASK<br>
56+
This method encapsulates a series of steps for conveniently creating and starting single task and callback task.
57+
</li><li><span style="color:#c0c0c0">XYZ.</span><span style="color:#808080">TPW_CALL.</span>WAIT_PJOB<br>
58+
Waits for all provided Tasks (parallel subtasks and callback task) of a pJob to complete execution.<br>
59+
To support this method, Oracle version utilizes the signaling mechanism come from SYS.DBMS_ALERT package; SQL Serverv version imitates it by a polling loop at present.
60+
</li></ol>
61+
<p>(XYZ is the schema name, it should be replaced by your schema name)</p>
62+
<p>Open the source code of Oracle package TPW_CALL <em>(or SQL Server stored procedures with prefix TPW_CALL_)</em> for detail parameters.</p>
63+
<p><strong>Status Inquiry</strong></p>
64+
<ul>
65+
<li>VIEW_TPW_PJOB<br>
66+
Displays pJobs' current status:<br>
67+
<img src="http://download-codeplex.sec.s-msft.com/Download?ProjectName=dbparallel&DownloadId=740495" alt="">
68+
<ul>
69+
<li>PJOB_STATE<br>
70+
Just current state. <em>(VIEW_TPW_WK_LOG provides historical state transitions)</em><br>
71+
Each pJob is born as CREATED state, and dies as ARCHIVED state. The real time state is visible during pJob's lifetime. Every pJob, irrespective of high or low ... the final state is equal -
72+
<span style="color:#808080">ARCHIVED</span>. </li><li>TASK_COUNT<br>
73+
The total number of parallel tasks contained in the pJob.<br>
74+
<em><span style="color:#808080">(not including any callback task - neither for success nor for fail)</span></em>
75+
</li><li>START_TIME<br>
76+
The actual time of when the pJob get started. </li><li>END_TIME<br>
77+
The actual time of when all parallel tasks of the pJob get completed. </li><li>FAILED_TASKS<br>
78+
How many parallel tasks failed under the pJob.<br>
79+
<em><span style="color:#808080">(not including any callback task - neither for success nor for fail)</span></em>
80+
</li></ul>
81+
</li><li>VIEW_TPW_TASK<br>
82+
Detail execution information about every parallel tasks.<br>
83+
<span style="color:#808080">(also including callback tasks - for success and for fail)</span>
84+
</li><li>VIEW_TPW_WK_LOG<br>
85+
History of pJobs' internal state transition.<br>
86+
<em><span style="color:#808080">[Old State] &gt;==Event==&gt; [New State]</span></em>
87+
</li></ul>
88+
<p><strong>How It's Made</strong></p>
89+
<ul>
90+
<li><span style="text-decoration:underline">Database Side</span><br>
91+
Each pJob is added into the Scheduler, and then the State Manager controls every stage in the lifecycle of the pJob.
92+
</li><li><span style="text-decoration:underline">Windows Service Side</span><br>
93+
At least one Pump Service must reside in Windows Services (or other hosting environment) act as a dispatcher, as shown in the following figure:
94+
</li></ul>
95+
<div style="padding-left:30px"><img src="http://download-codeplex.sec.s-msft.com/Download?ProjectName=dbparallel&DownloadId=371725" alt="" width="671" height="349" style="vertical-align:middle"></div>
96+
<p style="padding-left:30px">The dispatcher executes each of the provided tasks, possibly in parallel. No guarantees are made about the order in which the tasks execute or how many degree of parallelism. All tuning settings are located in TPW_PUMP_CONFIG table.<br>
97+
Each Task of a pJob is actually executed in the database through its separate connection. In other words, each Task runs in a different database session. Temporary table and transaction can not be expected to cross Tasks.</p>
98+
<p style="padding-left:30px"><em><span style="text-decoration:underline">Service Mode</span> - (Primary Mode | Standby Mode)</em></p>
99+
<div style="padding-left:30px">A Pump Service always starts up in Standby Mode. Multiple Standby Services can keep running for the same database, one of them will switch to Primary Mode when none Primary Service is active.</div>
100+
<div style="padding-left:150px"><img src="http://download-codeplex.sec.s-msft.com/Download?ProjectName=dbparallel&DownloadId=371727" alt="" width="577" height="387" style="vertical-align:middle"></div>
101+
<p><strong>Security Model</strong></p>
102+
<ul>
103+
<li>To create or operate a pJob:<br>
104+
The user must have EXECUTE privilege on the package TPW_CALL - for Oracle version;<br>
105+
<em>(Underlying stored procedures with prefix of &quot;TPW_CALL_&quot; for SQL Server version)</em>
106+
</li><li>To execute Task's SQL:<br>
107+
As a ultimate executor, the security account of Pump Service must have privileges to execute Tasks' SQL.
108+
</li></ul>
109+
<p><strong>Applicability</strong></p>
110+
<p style="padding-left:30px">The original intention of dbParallel is designed for time consuming database processing with one or more independent tasks can run concurrently. Not all processing is suitable for parallelization; for example, if a batch job performs
111+
only a small amount of work on each subtask, or it doesn't run for more than one second, then the overhead of parallelization can cause the processing to run more slowly. Besides, some special attention (e.g. locks, deadlocks, and race conditions) can not
112+
be ignored.</p>
113+
<p><strong>System Requirements</strong></p>
114+
<ul>
115+
<li>Supported Databases:
116+
<ul>
117+
<li>Oracle <span style="color:#808080">(dev and test on version 11g R1 and R2, hasn't try on earlier version)</span>;
118+
</li><li>SQL Server 2005 or later version; </li></ul>
119+
</li><li>Windows Service:
120+
<ul>
121+
<li>.NET Framework 4.0 Client Profile or higher versions </li></ul>
122+
</li><li>ADO.NET Provider:
123+
<ul>
124+
<li>Oracle
125+
<ul>
126+
<li>ODP.NET Managed Driver </li><li><em>Or</em> &nbsp; - ODP.NET 4 </li><li><em>Or</em> &nbsp; - DataDirect Connect for ADO.NET v3.5<br>
127+
<em>(the provider can be easily replaced by other provider for Oracle with the source code)</em>
128+
</li></ul>
129+
</li><li>SQL Server
130+
<ul>
131+
<li>.NET Framework build-in SqlClient provider. </li></ul>
132+
</li></ul>
133+
</li><li>Source Code:
134+
<ul>
135+
<li>Visual Studio 2010<a title="Microsoft Visual Studio 2010 Service Pack 1" href="http://www.microsoft.com/en-us/download/details.aspx?id=23691" target="_blank">SP1</a> or later versions
136+
</li><li><a title="Microsoft SQL Server Data Tools" href="http://msdn.microsoft.com/en-us/data/hh297027" target="_blank">SQL Server Data Tools (SSDT)</a>
137+
</li><li><a title="Installing NuGet" href="http://docs.nuget.org/docs/start-here/installing-nuget" target="_blank">NuGet Package Manager</a>
138+
</li></ul>
139+
</li></ul>
140+
<p style="padding-left:30px"><em>At present the dbParallel only support Oracle and SQL Server.</em></p>
141+
<p><strong>Contributions</strong></p>
142+
<ul>
143+
<li>Welcome all feedback through the CodePlex project (through comments, patches, or items in the Issue Tracker);
144+
</li></ul>
145+
<p><strong>Support</strong></p>
146+
<div style="padding-left:30px">Feel free to use the source in your apps, and products.<br>
147+
<br>
148+
This project is developed in personal time, the source code support can be available only at night - Easten Time (US &amp; Canada).</div>
149+
</div><div class="ClearBoth"></div>

‎docs/Home_VIEW_TPW_PJOB.png‎

10.8 KB
Loading

‎docs/Home_WorkPrinciple1.png‎

21.3 KB
Loading

‎docs/Home_WorkPrinciple2.png‎

44.6 KB
Loading

‎docs/Home_example1.png‎

7.73 KB
Loading

0 commit comments

Comments
 (0)