Skip to content

S
shrapnel
Commit 80d3701d authored by Sam Rushing's avatar Sam Rushing
Browse files
Options

second tutorial draft

parent f1b4b1c5
Hide whitespace changes
Inline Side-by-side
Showing with 1897 additions and 0 deletions
docs/shrapnel.svg 0 → 100644
View file @ 80d3701d
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="1052.3622"
height="744.09448"
id="svg2"
version="1.1"
inkscape:version="0.48.1 r9760"
sodipodi:docname="shrike.svg">
<defs
id="defs4">
<inkscape:perspective
sodipodi:type="inkscape:persp3d"
inkscape:vp_x="2.6642081 : 450.19734 : 1"
inkscape:vp_y="0 : 1000 : 0"
inkscape:vp_z="1047.9219 : 410.23422 : 1"
inkscape:persp3d-origin="526.18109 : 248.03149 : 1"
id="perspective3001" />
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="1.187804"
inkscape:cx="526.18109"
inkscape:cy="372.04724"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:window-width="1618"
inkscape:window-height="1252"
inkscape:window-x="103"
inkscape:window-y="110"
inkscape:window-maximized="0" />
<metadata
id="metadata7">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(0,-308.2677)">
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3913"
width="41.102364"
height="47.480316"
x="17.716541"
y="473.38577" />
<rect
style="fill:#b3b3b3;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.14044118;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3911"
width="41.10236"
height="52.440941"
x="17.007874"
y="691.6535" />
<rect
style="fill:#b3b3b3;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3017"
width="160.49298"
height="541.52734"
x="69.828453"
y="402.52829"
ry="0" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3029"
width="149.5751"
height="169.22731"
x="75.287399"
y="409.07901" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3031"
width="137.56543"
height="39.304409"
x="81.292229"
y="416.72153" />
<rect
y="462.00809"
x="81.292229"
height="39.304409"
width="137.56543"
id="rect3035"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.84482175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3039"
width="137.56543"
height="18.560415"
x="81.292229"
y="506.77145" />
<rect
y="529.69904"
x="80.200439"
height="39.304409"
width="139.74901"
id="rect3043"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.23911488;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
ry="0"
y="405.80365"
x="287.49896"
height="541.52734"
width="160.49298"
id="rect3813"
style="fill:#b3b3b3;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="411.2626"
x="292.95792"
height="148.48332"
width="149.5751"
id="rect3815"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.15158355;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="417.81335"
x="298.96277"
height="19.652199"
width="137.56543"
id="rect3817"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.86931431;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3819"
width="137.56543"
height="39.304409"
x="298.96277"
y="443.44769" />
<rect
y="488.21106"
x="298.96277"
height="57.864822"
width="137.56543"
id="rect3821"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.4916898;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3845"
width="149.5751"
height="169.22731"
x="632.32953"
y="329.88934" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3847"
width="137.56543"
height="39.304409"
x="638.33441"
y="337.53186" />
<rect
y="382.81845"
x="638.33441"
height="39.304409"
width="137.56543"
id="rect3849"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.84482175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3851"
width="137.56543"
height="18.560415"
x="638.33441"
y="427.58176" />
<rect
y="450.50937"
x="637.24261"
height="39.304409"
width="139.74901"
id="rect3853"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.23911488;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="469.14532"
x="805.21356"
height="61.140198"
width="149.5751"
id="rect3855"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.73895848;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="476.78784"
x="811.21838"
height="25.111151"
width="137.56543"
id="rect3857"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.98266286;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.67957491;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3859"
width="137.56543"
height="12.0097"
x="812.31018"
y="507.8811" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.02145195;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3865"
width="149.5751"
height="116.82144"
x="825.68091"
y="584.77936" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.00379777;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3867"
width="137.56543"
height="26.202938"
x="831.68573"
y="592.42194" />
<rect
y="623.5152"
x="831.68573"
height="53.497658"
width="137.56543"
id="rect3869"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.43429542;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.61469811;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3871"
width="137.56543"
height="9.8261023"
x="831.68573"
y="682.47186" />
<text
xml:space="preserve"
style="font-size:49.1758461px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="149.66675"
y="640.53827"
id="text3875"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
x="149.66675"
y="640.53827"
id="tspan3898"
style="text-align:center;text-anchor:middle">main</tspan><tspan
sodipodi:role="line"
x="149.66675"
y="702.00806"
style="text-align:center;text-anchor:middle"
id="tspan4014">stack</tspan></text>
<text
xml:space="preserve"
style="font-size:49.1758461px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="366.40079"
y="642.7218"
id="text3879"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3881"
x="366.40079"
y="642.7218">coro</tspan><tspan
sodipodi:role="line"
x="366.40079"
y="704.19159"
id="tspan3902">stack</tspan></text>
<text
xml:space="preserve"
style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="672.9906"
y="365.34204"
id="text3906"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3908"
x="672.9906"
y="365.34204">coro#0</tspan></text>
<text
xml:space="preserve"
style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="846.93707"
y="497.5014"
id="text3910"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3912"
x="846.93707"
y="497.5014">coro#1</tspan></text>
<text
xml:space="preserve"
style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="866.41394"
y="613.68134"
id="text3914"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3916"
x="866.41394"
y="613.68134">coro#2</tspan></text>
<text
xml:space="preserve"
style="font-size:19.67033958px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="260.99069"
y="972.79584"
id="text3918"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3920"
x="260.99069"
y="972.79584">swap() switches between running on the main</tspan><tspan
sodipodi:role="line"
x="260.99069"
y="997.38379"
id="tspan3922">stack and the coro stack.</tspan></text>
<text
xml:space="preserve"
style="font-size:17.21154594px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="234.41489"
y="634.64331"
id="text3924"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3926"
x="234.41489"
y="634.64331">swap()</tspan></text>
<path
id="path3930"
d="m 276.09164,651.43827 -6.15489,-4.89396 c -0.007,1.44704 -0.009,1.81022 -0.0131,2.53459 l -24.37018,0 c -0.004,-0.72445 -0.007,-1.08979 -0.0131,-2.5375 l -6.1549,4.89687 6.1549,4.89396 c 0.005,-1.54238 0.009,-1.97524 0.0131,-2.69227 l 24.37018,0 c 0.004,0.71703 0.009,1.14989 0.0131,2.69227 l 6.15489,-4.89396 z"
style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.10477623;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1"
inkscape:connector-curvature="0" />
<text
xml:space="preserve"
style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="102.32178"
y="490.02835"
id="text3932"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3934"
x="102.32178"
y="490.02835">scheduler</tspan></text>
<text
xml:space="preserve"
style="font-size:39.34067917px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="573.12317"
y="567.94855"
id="text3940"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3942"
x="573.12317"
y="567.94855">stack slice copies</tspan></text>
<text
xml:space="preserve"
style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="605.67572"
y="602.10406"
id="text3944"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3946"
x="605.67572"
y="602.10406">(potentially millions)</tspan></text>
<text
sodipodi:linespacing="125%"
id="text3952"
y="471.25784"
x="333.23474"
style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
xml:space="preserve"><tspan
y="471.25784"
x="333.23474"
id="tspan3954"
sodipodi:role="line">coro#n</tspan></text>
<text
xml:space="preserve"
style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="654.14832"
y="162.34866"
id="text3956"
sodipodi:linespacing="125%"
transform="translate(0,308.2677)"><tspan
sodipodi:role="line"
id="tspan3958"
x="654.14832"
y="162.34866" /></text>
<rect
y="814.81781"
x="516.99066"
height="169.22731"
width="149.5751"
id="rect3968"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="822.46033"
x="522.99554"
height="39.304409"
width="137.56543"
id="rect3970"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3972"
width="137.56543"
height="39.304409"
x="522.99554"
y="867.74695" />
<rect
y="912.51025"
x="522.99554"
height="18.560415"
width="137.56543"
id="rect3974"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.84482175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.23911488;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3976"
width="139.74901"
height="39.304409"
x="521.90375"
y="935.43787" />
<text
xml:space="preserve"
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="672.66986"
y="844.98657"
id="text3982"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3984"
x="672.66986"
y="844.98657">PyObject_Call (func=0x1002d8dd0, arg=0x1002eaec0, kw=0x0)</tspan></text>
<text
xml:space="preserve"
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="672.66986"
y="890.27319"
id="text3986"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3988"
x="672.66986"
y="890.27319">PyEval_CallObjectWithKeywords (func=0x1002d8dd0, ...)</tspan></text>
<text
xml:space="preserve"
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="672.66986"
y="924.66156"
id="text3990"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3992"
x="672.66986"
y="924.66156">PyEval_EvalFrameEx (f=0x10031f070, ...)</tspan></text>
<text
xml:space="preserve"
style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="672.66986"
y="957.96118"
id="text3994"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3996"
x="672.66986"
y="957.96118">PyEval_EvalCodeEx (co=0x10040a7b0, ...)</tspan><tspan
sodipodi:role="line"
x="672.66986"
y="972.96118"
id="tspan3998" /></text>
<text
xml:space="preserve"
style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="517.28607"
y="800.63715"
id="text4000"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan4002"
x="517.28607"
y="800.63715">stack frame</tspan></text>
<text
xml:space="preserve"
style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="109.74291"
y="926.07874"
id="text4004"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan4006"
x="109.74291"
y="926.07874">4MB</tspan></text>
<text
sodipodi:linespacing="125%"
id="text4008"
y="926.07874"
x="327.41342"
style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
xml:space="preserve"><tspan
y="926.07874"
x="327.41342"
id="tspan4010"
sodipodi:role="line">4MB</tspan></text>
<g
id="g4067"
transform="matrix(0.92221294,-0.38668242,0.38668242,0.92221294,-113.90628,266.46282)">
<path
inkscape:connector-curvature="0"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.20497175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
d="m 471.24729,456.37726 31.18686,10.23254 -6.99407,-7.32144 90.71753,0 0,-6.33834 -90.57701,0 6.85355,-7.52256 -31.18686,10.9498 z"
id="path4026" />
<text
sodipodi:linespacing="125%"
id="text4032"
y="444.51779"
x="511.86896"
style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
xml:space="preserve"><tspan
y="444.51779"
x="511.86896"
id="tspan4034"
sodipodi:role="line">resume</tspan></text>
</g>
<g
id="g3951">
<path
id="path4030"
d="m 604.83658,382.91221 -24.7521,21.55594 3.59606,-9.46514 -83.57577,35.28118 -2.46506,-5.83935 83.44631,-35.22653 -9.23962,-4.26491 32.99018,-2.04119 z"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.20497175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
inkscape:connector-curvature="0" />
<text
transform="matrix(0.9212747,-0.38891248,0.38891248,0.9212747,0,0)"
sodipodi:linespacing="125%"
id="text4036"
y="576.13635"
x="317.1749"
style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
xml:space="preserve"><tspan
y="576.13635"
x="317.1749"
id="tspan4038"
sodipodi:role="line">yield</tspan></text>
</g>
<g
id="g4048">
<flowRoot
style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Times New Roman;font-style:normal;font-weight:normal;font-size:12px;line-height:125%;letter-spacing:0px;word-spacing:0px;-inkscape-font-specification:Times New Roman"
id="flowRoot4040"
xml:space="preserve"><flowRegion
id="flowRegion4042"><rect
y="103.41638"
x="467.24881"
height="78.295746"
width="123.75779"
id="rect4044" /></flowRegion><flowPara
id="flowPara4046" /></flowRoot> </g>
<flowRoot
xml:space="preserve"
id="flowRoot4054"
style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Times New Roman;font-style:normal;font-weight:normal;font-size:12px;line-height:125%;letter-spacing:0px;word-spacing:0px;-inkscape-font-specification:Times New Roman"><flowRegion
id="flowRegion4056"><rect
id="rect4058"
width="140.59558"
height="90.082199"
x="460.5137"
y="93.313705" /></flowRegion><flowPara
id="flowPara4060" /></flowRoot> <rect
y="665.60077"
x="698.55554"
height="12.273481"
width="15.714643"
id="rect4072"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.10731567;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.16018762;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4074"
width="23.456882"
height="18.320341"
x="738.12439"
y="651.28864" />
<rect
y="720.32361"
x="701.9231"
height="22.529789"
width="28.846548"
id="rect4076"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.1969938;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.13074268;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4078"
width="19.145149"
height="14.952783"
x="733.073"
y="695.06689" />
<rect
y="691.69934"
x="772.64178"
height="10.958413"
width="14.030864"
id="rect4080"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.0958171;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.29129282;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4082"
width="42.655113"
height="33.314583"
x="766.7486"
y="722.84924" />
<rect
y="720.26825"
x="832.41602"
height="43.835133"
width="56.125347"
id="rect4084"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.38328138;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="646.2373"
x="716.23523"
height="7.1422563"
width="9.1447563"
id="rect4086"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.06244976;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="626.03192"
x="739.80817"
height="5.8271875"
width="7.4609771"
id="rect4088"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.05095119;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.05095119;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4090"
width="7.4609771"
height="5.8271875"
x="711.1839"
y="628.55762" />
<rect
y="633.60895"
x="695.18799"
height="3.3015182"
width="4.2271767"
id="rect4092"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02886749;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="732.11011"
x="854.30518"
height="59.572937"
width="76.275627"
id="rect4094"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.52088809;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
y="736.00745"
x="857.36731"
height="13.362153"
width="70.151306"
id="rect4096"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.51188534;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.73141706;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4098"
width="70.151306"
height="27.281059"
x="857.36731"
y="751.8634" />
<rect
y="781.92828"
x="857.36731"
height="5.010808"
width="70.151306"
id="rect4100"
style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.31346449;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<text
sodipodi:linespacing="125%"
id="text4102"
y="746.84863"
x="875.0769"
style="font-size:12.53857899px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
xml:space="preserve"><tspan
y="746.84863"
x="875.0769"
id="tspan4104"
sodipodi:role="line">coro#3</tspan></text>
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.04877656;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4106"
width="7.1425371"
height="5.5784788"
x="679.19208"
y="653.81433" />
<rect
y="641.9082"
x="681.87097"
height="3.486217"
width="4.4636602"
id="rect4108"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.03048244;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4110"
width="2.9753954"
height="2.3238494"
x="682.46625"
y="629.4068" />
<rect
y="625.23969"
x="687.52637"
height="2.3238494"
width="2.9753954"
id="rect4112"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4114"
width="2.9753954"
height="2.3238494"
x="698.53955"
y="625.83496" />
<rect
y="621.07251"
x="695.56305"
height="2.3238494"
width="2.9753954"
id="rect4116"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<rect
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect4118"
width="2.9753954"
height="2.3238494"
x="714.91052"
y="618.09601" />
<rect
y="616.01245"
x="701.81378"
height="2.3238494"
width="2.9753954"
id="rect4120"
style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<text
xml:space="preserve"
style="font-size:12px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="36.372467"
y="486.14166"
id="text3125"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3127"
x="36.372467"
y="486.14166">Used</tspan><tspan
sodipodi:role="line"
x="36.372467"
y="501.14166"
id="tspan3129">Stack</tspan><tspan
sodipodi:role="line"
x="36.372467"
y="516.14166"
id="tspan3131">Area</tspan></text>
<text
xml:space="preserve"
style="font-size:12px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="36.735748"
y="706.5354"
id="text3133"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3135"
x="36.735748"
y="706.5354">Unused</tspan><tspan
sodipodi:role="line"
x="36.735748"
y="721.5354"
id="tspan3137">Stack</tspan><tspan
sodipodi:role="line"
x="36.735748"
y="736.53546"
id="tspan3139">Area</tspan><tspan
sodipodi:role="line"
x="36.735748"
y="751.53546"
id="tspan3141" /></text>
<text
sodipodi:linespacing="125%"
id="text3938"
y="396"
x="109.33276"
style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
xml:space="preserve"><tspan
y="396"
x="109.33276"
id="tspan3940"
sodipodi:role="line">0MB</tspan></text>
<text
xml:space="preserve"
style="font-size:14px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="569.5769"
y="-32.028229"
id="text3942"
sodipodi:linespacing="125%"
transform="matrix(0,1,-1,0,0,0)"><tspan
sodipodi:role="line"
id="tspan3944"
x="569.5769"
y="-32.028229">Stack Growth</tspan></text>
<path
id="path3949"
d="m 34.496003,649.45247 -6.4113,-9.75108 4.61419,2.14152 0.15907,-28.63263 4.00522,-0.0572 -0.15883,28.58826 4.76555,-2.23095 -6.9739,9.94202 z"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.09153501;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
inkscape:connector-curvature="0" />
<text
xml:space="preserve"
style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
x="327.0033"
y="395.29135"
id="text3957"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan3959"
x="327.0033"
y="395.29135">0MB</tspan></text>
</g>
</svg>
docs/style.css 0 → 100644
View file @ 80d3701d
body {
margin-left: 1.0em;
margin-top: 1.0em;
background-color: #b8ccb8;
font-family: Helvetica, Arial, FreeSans, san-serif;
color: #00000;
}
container {
margin: 0 auto;
width: 700px;
}
h1 { font-size: 3.0em; color: #102750; margin-bottom: 3px; }
h1 .small { font-size: 0.4em; }
h1 a { text-decoration: none }
h2 { font-size: 1.5em; color: #102750; }
h3 { text-align: center; color: #102750; }
a { color: #102750; }
.description { font-size: 1.2em; margin-bottom: 30px; margin-top: 30px; font-style: italic;}
.download { float: right; }
pre { background: #fff; color: #000; padding: 15px;}
hr { border: 0; width: 80%; border-bottom: 1px solid #aaa}
.footer { text-align:center; padding-top:30px; font-style: italic; }
docs/tutorial.rst 0 → 100644
View file @ 80d3701d
=============================
Getting Started with Shrapnel
=============================
:Date: $Date: 2012/03/30 $
:Author: Sam Rushing
.. contents::
:depth: 2
:backlinks: top
.. section-numbering::
Shrapnel/Coro is a highly scalable cooperative threading facility for CPython.
Intro
=====
Shrapnel is a library for high-performance concurrency. It uses
coroutines to implement user threads on top of either kqueue (FreeBSD,
OS X) or /dev/epoll (linux), and is written mostly in Pyrex/Cython,
supporting both 32-bit and 64-bit platforms. It is the culmination of
about 8 years of work at IronPort Systems, a provider of high-speed
mail appliances. It was open-sourced by Cisco Systems in late 2011.
Features
--------
* Lightweight threads, event-driven scheduler.
* Underneath: non-blocking operations on descriptors, like sockets and pipes.
* On top, synchronous API for straight-line, simple code.
* Highly scalable - tens or hundreds of thousands of connections/threads.
* Thread synchronization primitives, like mutexes, semaphores, etc...
* Wait on kqueue events like file/directory changes, signals, processes, etc... [kqueue only]
* DNS stub resolver (full-fledged resolver may be forthcoming)
* HTTP server and client
* RPC system
* Support for TLS via tlslite (openssl interface may be forthcoming)
* other protocols/codecs: ldap, asn1, ftp, mysql, postgres, AMQP_.
* `MIT License`_.
.. _MIT License: http://www.opensource.org/licenses/mit-license.html
.. _AMQP: https://github.com/samrushing/amqp-shrapnel
The Name
--------
`Shrapnel` is the name of the implementation. The python package that
it implements is ``coro``. It's actually the third implementation of
the coro package written at IronPort - previous versions were written
in C using a painful type of continuation-passing style, and relied on
variants of Stackless Python.
Installing
----------
Requirements:
* Cython (>=0.12.1)
* distribute (>=0.6.16)
Install with::
$ pip install coro
*or* alternatively download shrapnel from
https://github.com/ironport/shrapnel and do the usual ``setup.py`` procedure::
$ git clone git://github.com/ironport/shrapnel.git
$ cd shrapnel
$ python setup.py build
$ [sudo] python setup.py install
Basics
======
Event Loop
----------
Everything runs in the event loop. So the last thing your ``__main__`` script will do is always::
coro.event_loop()
Calling this function starts the scheduler, which enters a loop continually running threads that are ready to run, feeding new waitable events to the operating system, and waiting for events to be triggered. When an event is triggered, the thread waiting on that event is awakened.
Interaction
-----------
Because everything runs in the event loop, you can't interact with the normal python prompt. But you can interact via the 'backdoor'. The backdoor interface is crucial to development with shrapnel. It allows you to open one or more telnet sessions into the system and interact with a python prompt there. So a common pattern in __main__ is this:
.. sourcecode:: python
if __name__ == '__main__':
import coro
import coro.backdoor
coro.spawn (coro.backdoor.serve, unix_path='/tmp/xx.bd')
coro.event_loop()
Once this is running, open another terminal window and::
$ telnet /tmp/xx.bd
[It's important to use the full path, you can't cd into /tmp and ``"$telnet xx.bd"``.]
Go ahead and run ``shrapnel/docs/tutorial/t0.py`` now, we'll use it in the following demonstration::
$ cd shrapnel/docs/tutorial/
$ python t0.py
1: Sat Mar 31 16:28:44 2012 Backdoor started on unix socket /tmp/xx.bd
In another window::
$ telnet /tmp/xx.bd
Trying /tmp/xx.bd...
Connected to (null).
Escape character is '^]'.
Python 2.7.2 (default, Mar 10 2012, 12:30:07)
[GCC 4.2.1 Compatible Clang 3.1 (trunk 149115)]
Copyright (c) 2001-2011 Python Software Foundation.
All Rights Reserved. [etc]
>>>
Output
------
Note the behavior of I/O to sys.stdout/stderr when using the back door::
>>> print "Howdy"
Howdy
and::
>>> sys.stdout.write ("Hello\n")
Hello
>>>
i.e, they print to the terminal, not the main console.
To send debugging output to the *console*, use ``coro.write_stderr()`` and ``coro.print_stderr()``.
Skullduggery
------------
From the back door you can poke around in the internals of the system while it's running::
>>> coro.event_map
{<kevent_key filter=-1 ident=4>: <kevent_target status=1 index=0 target=<coro #1 name='<function serve at 0x1007e1de8>' dead=0 started=1 scheduled=0 at 0x1005c1500> flags=0>, ...}
>>>
>>>
>>> coro.where_all()
{1: ('<function serve at 0x1007e1de8>', <coro #1 name='<function serve at 0x1007e1de8>' dead=0 started=1 scheduled=0 at 0x1005c1500>, '[coro/backdoor.py serve|224]'), ...}
>>>
>>> player_db['annoying_guy23'].demote()
<player annoying_guy23 id=394203 level=peon>
>>>
Sleeping
--------
The sleep_relative() function allow you to put a thread to sleep for a time::
>>> coro.sleep_relative (5)
[5 second pause]
>>>
Starting a New Thread
---------------------
Start a new thread with ``coro.spawn()``::
>>> def thing():
... for x in range (10):
... coro.write_stderr ('%d\n' % (x,))
... coro.sleep_relative (1)
...
>>> coro.spawn (thing)
<coro #5 name='<function thing at 0x10152af50>' dead=0 started=0 scheduled=1 at 0x1005f97b0>
>>>
In the main window you should see a new digit printed every second.
``coro.spawn()`` takes a callable object, args, and keyword args:
.. sourcecode:: python
coro.spawn (fun0, arg0, arg1, kwd0=val0, kwd1=val1)
Starting A *Lot* of New Threads
-------------------------------
Start up 1000 threads::
>>> import random
>>> def thing():
... t = random.randrange (0, 15)
... coro.sleep_relative (t)
... coro.write_stderr ('*')
...
>>> for x in range (1000):
... coro.spawn (thing)
...
>>>
Over the next 15 seconds you should see groups of ``'*'`` characters sent to the main window.
Servers and Clients
===================
Echo Server
-----------
Creating a server is easy (see `docs/tutorial/t1.py`_):
.. sourcecode:: python
import coro
import coro.backdoor
def session (conn, addr):
while 1:
block = conn.recv (1000)
if not block:
break
else:
conn.send (block)
def serve (port=9000):
s = coro.tcp_sock()
s.bind (('', port))
s.listen (50)
while 1:
conn, addr = s.accept()
coro.spawn (session, conn, addr)
if __name__ == '__main__':
coro.spawn (coro.backdoor.serve, unix_path='/tmp/xx.bd')
coro.spawn (serve)
coro.event_loop()
.. _docs/tutorial/t1.py: tutorial/t1.py
You can telnet into that server::
$ telnet localhost 9000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
asdf
asdf
asdf
asdf
asdf
[Hit ``Ctrl-], c, <return>`` to close the connection]
Timeouts
--------
One of the nicer features of shrapnel is ``with_timeout()``. Use
``with_timeout()`` around any function call:
.. sourcecode:: python
result = thing.db.query ("SELECT * FROM CANDYBIN;")
with a 30-second timeout becomes:
.. sourcecode:: python
result = coro.with_timeout (30, thing.db.query, "SELECT * FROM CANDYBIN;")
If the function hasn't returned within 30 seconds, it will raise
``coro.TimeoutError``:
.. sourcecode:: python
try:
r = coro.with_timeout (30, function, arg0, arg1, ...)
except coro.TimeoutError:
coro.write_stderr ("Hey, that took too long!\n")
Multiple layers of timeouts work as expected.
.. note::
Try editing the echo server from above, adding a timeout to the
``conn.recv (1000)`` call. Make it so that it exits the loop and
closes the connection if nothing is typed within 10 seconds.
Exiting The Event Loop
----------------------
You can tell the system to exit::
>>> coro.set_exit()
>>> Connection closed by foreign host.
.. note::
Try editing the echo server from above, so that it'll exit the
event loop when it receives the string 'quit\\r\\n'.
Echo Client
-----------
It's difficult to really beat on that server with your own fingers (and telnet).
How about a client that'll exercise it a little (see `docs/tutorial/t2.py`_):
.. sourcecode:: python
import coro
def client (ip='127.0.0.1', port=9000):
global alive
alive += 1
try:
s = coro.tcp_sock()
s.connect ((ip, port))
for i in range (10):
s.send ('howdy there\r\n')
assert (s.recv_exact (13) == 'howdy there\r\n')
coro.write_stderr ('.')
s.close()
finally:
alive -= 1
if alive == 0:
coro.write_stderr ('\ndone.\n')
coro.set_exit()
if __name__ == '__main__':
alive = 0
for i in range (100):
coro.spawn (client)
coro.event_loop()
.. _docs/tutorial/t2.py: tutorial/t2.py
Hit Ctrl-C to exit.
You should just see a hundred dots in the main window. You might get connection reset errors if the listen() parameter in the server wasn't high enough. If so, you could put some calls to sleep_relative() in there to stagger the creation of the clients.
Proxy Server
------------
This is a handy little server that lets you 'spy' on protocols. It's
very handy when implementing protocols. See `docs/tutorial/proxy.py`_.
.. _docs/tutorial/proxy.py: tutorial/proxy.py
.. sourcecode:: python
import coro
W = coro.write_stderr
class session:
counter = 0
def __init__ (self, conn, addr, saddr):
self.conn = conn
self.addr = addr
self.saddr = saddr
self.id = session.counter
session.counter += 1
self.proxy = coro.tcp_sock()
self.proxy.connect (saddr)
coro.spawn (self.feed, self.conn, self.proxy, '<==')
coro.spawn (self.feed, self.proxy, self.conn, '==>')
def feed (self, c0, c1, dir):
try:
while 1:
block = c0.recv (1000)
W ('%s %d %r\n' % (dir, self.id, block))
if not block:
break
else:
c1.send (block)
finally:
c0.close()
def serve (saddr):
ip, port = saddr
s = coro.tcp_sock()
s.bind (('0.0.0.0', port + 9000))
s.listen (5)
while 1:
conn, caddr = s.accept()
coro.spawn (session, conn, caddr, saddr)
if __name__ == '__main__':
import sys
if len (sys.argv) < 3:
print 'Usage: %s <server-host> <server-port>' % sys.argv[0]
else:
coro.spawn (serve, (sys.argv[1], int (sys.argv[2])))
coro.event_loop()
Let's say you want to spy on an HTTP connection::
$ python proxy.py 72.52.84.226 80
The proxy works by adding 9000 to the port number you're connecting to.
Try this link: http://localhost:9080/tutorial_hello.html
Profiler
========
Shrapnel comes with an efficient and comprehensive profiler that
accounts for the resources used by each thread. On most platforms it
uses the RDTSC instruction to gather accurate timings with low
overhead. It profiles both Python and Cython code:
.. sourcecode:: python
import coro.profiler
#coro.event_loop()
coro.profiler.go (coro.event_loop)
By default it collects data from the ``rusage()`` facility and RDTSC,
see the documentation for details.
When the function you are profiling has exited, it will dump a binary
file containing the results (default: ``/tmp/coro_profile.bin``),
which you can post-process using the ``coro.print_profile`` module::
$ python coro/print_profile.py /tmp/coro_profile.bin > /tmp/p0.html
Pull that up in your browser, you'll find aggregate and non-aggregate tables, along with a call graph.
Non-Aggregate Timings
+------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
|calls | ticks |ticks/call | utime | utime/call | stime | stime/call | minflt | majflt | oublock | msgsnd | msgrcv | Function |
+======+====================+===============+===================+=====================+===================+==================+===============+=========+=========+========+========+=====================================+
|0 | 29552069532 | 29552069532 |0.022320 | 0.02232 | 0.031529 | 0.031529 | 0 | 0 | 0 | 0 | 0 | <wait> |
+------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
|4540 |299809652 (15.86%) | 66037 |0.118307 (16.70%) | 0.000026 | 0.013881 (10.17%) | 0.000003 | 2 (4.88%) | 0 | 0 | 0 | 0 | python/worms.py:move:141 |
+------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
|0 | 227071913 (12.01%) | 227071913 |0.093381 (13.18%) | 0.093381 | 0.010697 (7.84%) | 0.010697 | 3 (7.32%) | 0 | 0 | 0 | 0 | <main> |
+------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
|4783 |192461416 (10.18%) | 40238 |0.072527 (10.24%) | 0.000015 | 0.012591 (9.22%) | 0.000003 | 1 (2.44%) | 0 | 0 | 0 | 0 | python2.7/random.py:randrange:173 |
+------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
|2420 | 171570517 (9.08%) | 70896 |0.069622 (9.83%) | 0.000029 | 0.006048 (4.43%) | 0.000002 | 1 (2.44%) | 0 | 0 | 0 | 0 | python/worms.py:draw:185 |
+------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
From the call graph section::
__builtin__:dict.has_key -- ticks=15234 utime=6e-06 stime=1e-06
3/3 (100.0%) coro/__init__.py:spawn:337
3 __builtin__:dict.has_key
__builtin__:file.write -- ticks=263623 utime=4.1e-05 stime=7.5e-05
7/7 (100.0%) python/worms.py:status:230
7 __builtin__:file.write
__builtin__:len -- ticks=28508261 utime=0.010467 stime=0.002547
14/4884 (00.3%) python/worms.py:status:230
330/4884 (06.8%) python2.7/random.py:choice:272
4540/4884 (93.0%) python/worms.py:move:141
4884 __builtin__:len
[...]
Example of the full `profiler output`_. Note: each graph may be [re]sorted by clicking on a column header.
.. _profiler output: sample_profile.html
The Killer Demo
===============
See `docs/tutorial/worms.py`_ for a fun demo. Run the script from
one terminal, and telnet into it from another terminal with a nice
large window (your terminal needs to support ANSI escape codes).
Each worm is its own thread, and each socket client has a separate
view into the shared 'arena'. This demo can easily handle hundreds of
separate worms (though things tend to get crowded)::
+=========================================================================+
| **********d|
| 9 |
| 9 |
| 9 |
| 9 |
| 9 |
| 9 |
| 9 |
| 9 |
| 9 |
| 9 |
| 9 |
| |
| |
| b a |
| b a |
| b a |
| b a 1 |
| eeeeee b a 1 |
| e b a 1 |
| e b a1111111 |
| e b a1 |
| e b a |
| e b a |
| b a |
| f |
| f |
| f |
| f |
| f |
| ffffff |
+=========================================================================+
keys: [q]uit [r]edraw [n]ew [c]ull [l]engthen [h]offa
.. _docs/tutorial/worms.py: tutorial/worms.py
Here's the code controlling each worm's movement:
.. sourcecode:: python
def go (self):
try:
while not self.exit:
coro.sleep_relative (self.speed / 10000.0)
if random.randrange (0,20) == 10:
if not self.turn():
return
else:
nx, ny = self.update()
while self.arena[(nx,ny)] != ' ':
if not self.turn():
return
nx, ny = self.update()
self.move ((nx, ny))
finally:
self.arena.worms.remove (self)
To come: a separate tutorial on hardening servers against attack. I
think this would be a great example to work with.
Details
=======
Exceptions
----------
What happens when there's an unhandled exception in a thread?::
>>> def thing():
... return 1/0
...
>>> coro.spawn (thing)
<coro #205 name='<function thing at 0x1007e6758>' dead=0 started=0 scheduled=1 at 0x1005cf040>
>>>
You should see something like this in the main window::
205: Sat Mar 31 17:29:06 2012 thread 205 (<function thing at 0x1007e6758>): error
'(\'<coro.backdoor.backdoor instance at 0x1007decf8> thing|2\',
"<type \'exceptions.ZeroDivisionError\'>", \'integer division or modulo by zero\',
\'[_coro.pyx coro._coro._wrap1 (coro/_coro.c:8821)|800] [<coro.backdoor.backdoor instance at 0x1007decf8> thing|2]\')'
The default exception handler for a thread prints a timestamp, some info about the thread that crashed, and a compact, one-line traceback.
You can replace the default handler with ``coro.set_exception_notifier()``.
Latency Warnings
----------------
It's important that no thread monopolizes the CPU for too long. This
can happen if you inadvertently call a blocking system function (e.g.,
filesystem I/O). To assist you in finding bugs that do this, the
scheduler will print out a warning like this::
Wed Apr 4 00:29:01 2012 High Latency: (5.449s) for <coro #4 name='mp4 encoder' at 0x1003ceaa0>
Any thread that holds the CPU for more than 0.2s will trigger the
warning. You can change the trigger value with ``coro.set_latency_warning()``.
SimultaneousError
-----------------
If two threads try to perform the same I/O operation (technically,
wait on the same kevent), this will trigger a ``SimultaneousError``::
>>> coro.x.recv (100)
Traceback (most recent call last):
File "/usr/local/lib/python2.7/site-packages/coro/backdoor.py", line 144, in parse
result = eval (co, env)
File "<coro.backdoor.backdoor instance at 0x100624ef0>", line 1, in <module>
File "socket.pyx", line 580, in coro._coro.sock.recv (coro/_coro.c:20208)
File "socket.pyx", line 1113, in coro._coro.sock._wait_for_read (coro/_coro.c:23549)
File "poller.pyx", line 326, in coro._coro.queue_poller._wait_for_read (coro/_coro.c:15292)
File "poller.pyx", line 318, in coro._coro.queue_poller._wait_for_with_eof (coro/_coro.c:15204)
File "poller.pyx", line 342, in coro._coro.queue_poller._wait_for (coro/_coro.c:15516)
File "poller.pyx", line 304, in coro._coro.queue_poller.set_wait_for (coro/_coro.c:15056)
SimultaneousError: <SimultaneousError co=<coro #6 name='backdoor session' dead=0 started=1 scheduled=0 at 0x1003ceaa0> other=<coro #5 name='backdoor session' dead=0 started=1 scheduled=0 at 0x1003d0080> event=<kevent_key filter=-1 ident=0>>
>>>
You can easily avoid this problem by isolating particular events to
their own thread. For example, you can have one thread that *reads*
from a socket, while another *writes* to it. You can combine
identical events from multiple threads by using one of the
synchronization primitives. A common idiom uses a ``coro.fifo``:
.. sourcecode:: python
def writer (self):
while not self.exit:
data = self.fifo.pop()
if data is None:
break
else:
self.conn.send (data)
In this example we use a sentinel (``None``) to force the fifo to wake
up and exit the loop. This is similar to a generator's use of ``StopIteration``.
Things To Avoid
---------------
Blocking calls. Slow file I/O. Not closing descriptors. *Threads*. etc.
How it Works
------------
Shrapnel works by using two (or more) C stacks. The first stack (the
default one from libc) runs the scheduler, which is responsible for
switching out coro threads, managing the timed-events queue, and
calling kevent (or hitting /dev/epoll). The second stack is where
coro threads run. When it's time for a thread to run, its stack
contents are copied from the heap onto the second stack, and a small
amount of assembly code (similar to the ``ucontext`` facility)
resumes it. When a thread yields, the portion of the stack used by
that thread is evacuated into the heap.
.. image:: shrapnel.svg
This design allows Shrapnel to work with a completely stock CPython.
It has been used continuously with Python 2.3 to 2.7, and can usually
be linked as a shared library against the platform's OEM install of
Python.
Credits
=======
[Get a comprehensive list of everyone that's contributed to shrapnel,
maybe with home page links?]
..
Local Variables:
compile-command: "rst2html.py --embed-stylesheet --stylesheet-path=style.css tutorial.rst tutorial.html"
End:
docs/tutorial/proxy.py 0 → 100644
View file @ 80d3701d
# -*- Mode: Python -*-
import coro
W = coro.write_stderr
class session:
counter = 0
def __init__ (self, conn, addr, saddr):
self.conn = conn
self.addr = addr
self.saddr = saddr
self.id = session.counter
session.counter += 1
self.proxy = coro.tcp_sock()
self.proxy.connect (saddr)
coro.spawn (self.feed, self.conn, self.proxy, '<==')
coro.spawn (self.feed, self.proxy, self.conn, '==>')
def feed (self, c0, c1, dir):
try:
while 1:
block = c0.recv (1000)
W ('%s %d %r\n' % (dir, self.id, block))
if not block:
break
else:
c1.send (block)
finally:
c0.close()
def serve (saddr):
ip, port = saddr
s = coro.tcp_sock()
s.bind (('0.0.0.0', port + 9000))
s.listen (5)
while 1:
conn, caddr = s.accept()
coro.spawn (session, conn, caddr, saddr)
if __name__ == '__main__':
import sys
if len (sys.argv) < 3:
print 'Usage: %s <server-host> <server-port>' % sys.argv[0]
else:
coro.spawn (serve, (sys.argv[1], int (sys.argv[2])))
coro.event_loop()
docs/tutorial/t0.py 0 → 100644
View file @ 80d3701d
import coro
import coro.backdoor
coro.spawn (coro.backdoor.serve, unix_path='/tmp/xx.bd')
coro.event_loop()
docs/tutorial/t1.py 0 → 100644
View file @ 80d3701d
# -*- Mode: Python -*-
import coro
import coro.backdoor
def session (conn, addr):
while 1:
block = conn.recv (1000)
if not block:
break
else:
conn.send (block)
def serve (port=9000):
s = coro.tcp_sock()
s.bind (('', port))
s.listen (50)
while 1:
conn, addr = s.accept()
coro.spawn (session, conn, addr)
if __name__ == '__main__':
coro.spawn (coro.backdoor.serve, unix_path='/tmp/xx.bd')
coro.spawn (serve)
coro.event_loop()
docs/tutorial/t2.py 0 → 100644
View file @ 80d3701d
# -*- Mode: Python -*-
import coro
def client (ip='127.0.0.1', port=9000):
global alive
alive += 1
try:
s = coro.tcp_sock()
s.connect ((ip, port))
for i in range (10):
s.send ('howdy there\r\n')
assert (s.recv_exact (13) == 'howdy there\r\n')
coro.write_stderr ('.')
s.close()
finally:
alive -= 1
if alive == 0:
coro.write_stderr ('\ndone.\n')
coro.set_exit()
if __name__ == '__main__':
alive = 0
for i in range (100):
coro.spawn (client)
coro.event_loop()
docs/tutorial/t3.py 0 → 100644
View file @ 80d3701d
# -*- Mode: Python -*-
import coro
import coro.backdoor
import sys
import curses
import pyximport
pyximport.install()
sys.path.append ('/Users/rushing/src/cython')
import newterm
def session (conn, addr):
while 1:
block = conn.recv (1000)
if not block:
break
else:
conn.send (block)
def serve (port=9000):
s = coro.tcp_sock()
s.bind (('', port))
s.listen (50)
while 1:
conn, addr = s.accept()
coro.spawn (session, conn, addr)
if __name__ == '__main__':
coro.spawn (coro.backdoor.serve, unix_path='/tmp/xx.bd')
coro.spawn (serve)
coro.event_loop()
docs/tutorial/worms.py 0 → 100644
View file @ 80d3701d
# -*- Mode: Python -*-
# http://en.wikipedia.org/wiki/ANSI_escape_code
import array
import coro
import math
W = coro.write_stderr
CSI = '\x1B['
at_format = CSI + '%d;%dH%s' # + CSI + '0m'
def at (x, y, ch):
return at_format % (y, x, ch)
import random
class arena:
def __init__ (self, w=150, h=53):
self.w = w
self.h = h
self.data = [ array.array ('c', " " * w) for y in range (h) ]
# put some walls around the outside
for i in range (w):
self.data[0][i] = '='
self.data[-1][i] = '='
for j in range (h):
self.data[j][0] = '|'
self.data[j][-1] = '|'
self.data[0][0] = '+'
self.data[0][-1] = '+'
self.data[-1][0] = '+'
self.data[-1][-1] = '+'
self.worms = []
self.listeners = []
def random_pos (self):
while 1:
x = random.randrange (1, self.w-1)
y = random.randrange (1, self.h-1)
if self[x,y] == ' ':
break
return x, y
def render (self):
return '\n'.join (x.tostring() for x in self.data)
def __getitem__ (self, (x, y)):
return self.data[y][x]
def draw (self, pos, chr='*'):
x, y = pos
if self.data[y][x] in "=|+":
import pdb; pdb.set_trace()
self.data[y][x] = chr
for lx in self.listeners:
lx.draw (pos, chr)
def erase (self, pos):
x, y = pos
self.data[y][x] = ' '
for lx in self.listeners:
lx.erase (pos)
def populate (self, n=5):
for i in range (n):
x, y = self.random_pos()
self.worms.append (worm (self, x, y))
def cull (self, hoffa=False):
for worm in self.worms:
if worm.stunned:
W ('culling worm %r\n' % (worm.chr,))
worm.kill (hoffa)
class worm:
counter = 0
# up down left right
movex = [0,0,-1,1]
movey = [-1,1,0,0]
def __init__ (self, arena, x, y, length=10):
self.arena = arena
self.head = x, y
self.tail = []
self.dir = random.randrange (0, 4)
self.length = length
worm.counter += 1
self.chr = '0123456789abcdefghijklmnopqrstuvwxyz'[worm.counter%36]
self.speed = random.randrange (200, 400)
self.exit = False
self.stunned = False
W ('new worm %r @ %d, %d speed=%d\n' % (self.chr, x, y, self.speed))
coro.spawn (self.go)
def go (self):
try:
while not self.exit:
coro.sleep_relative (self.speed / 10000.0)
if random.randrange (0,20) == 10:
if not self.turn():
return
else:
nx, ny = self.update()
while self.arena[(nx,ny)] != ' ':
if not self.turn():
return
nx, ny = self.update()
self.move ((nx, ny))
finally:
self.arena.worms.remove (self)
def update (self):
x, y = self.head
return (
x + self.movex[self.dir],
y + self.movey[self.dir]
)
def turn (self):
while not self.exit:
x, y = self.head
a = self.arena
choices = []
for i in range (4):
nx = x + self.movex[i]
ny = y + self.movey[i]
if a[nx,ny] == ' ':
choices.append (i)
if not choices:
return self.stun()
else:
self.dir = random.choice (choices)
return True
def stun (self):
self.stunned = True
for pos in self.tail:
self.arena.draw (pos, '*')
coro.sleep_relative (5)
self.stunned = False
return not self.exit
def move (self, pos):
self.tail.append (self.head)
self.head = pos
self.arena.draw (pos, self.chr)
if len (self.tail) > self.length:
tpos = self.tail.pop (0)
self.arena.erase (tpos)
def kill (self, hoffa=True):
self.arena.erase (self.head)
for pos in self.tail:
if hoffa:
self.arena.draw (pos, '#')
else:
self.arena.erase (pos)
self.exit = True
self.head = (None, None)
self.tail = []
class terminal:
def __init__ (self, conn):
self.conn = conn
self.conn.send (
'\xff\xfc\x01' # IAC WONT ECHO
'\xff\xfb\x03' # IAC WILL SUPPRESS_GO_AHEAD
'\xff\xfc"' # IAC WONT LINEMODE
)
# turn off the cursor
self.conn.send (CSI + '?25l')
self.fifo = coro.fifo()
self.redraw()
self.t0 = coro.spawn (self.listen)
self.t1 = coro.spawn (self.writer)
self.exit = False
def redraw (self):
self.fifo.push (''.join ([
# clear the screen
CSI + '2J',
# move to home
CSI + '1;1H',
# draw the arena
the_arena.render(),
'\n keys: [q]uit [r]edraw [n]ew [c]ull [l]engthen [h]offa\n',
]))
def draw (self, (x, y), chr):
chr = (
CSI
+ '%dm' % (40+ord(chr)%8,)
+ CSI
+ '%dm' % (30+ord(chr)%7,)
+ chr
+ CSI
+ '0m'
)
self.fifo.push (at (x+1, y+1, chr))
def erase (self, (x, y)):
self.fifo.push (at (x+1, y+1, ' '))
def writer (self):
while not self.exit:
data = self.fifo.pop()
if data is None:
break
else:
self.conn.send (data)
def listen (self):
while not self.exit:
byte = self.conn.recv (1)
if byte == '\xff':
# telnet stuff, dump it
self.conn.recv (2)
elif byte == 'r':
self.redraw()
elif byte == 'n':
the_arena.populate (1)
elif byte == 'c':
the_arena.cull()
elif byte == 'l':
for worm in the_arena.worms:
worm.length += 1
elif byte == 'h':
the_arena.cull (hoffa=True)
elif byte == 'q':
self.exit = True
# turn the cursor back on...
self.conn.send (CSI + '?25h')
the_arena.listeners.remove (self)
self.conn.close()
self.fifo.push (None)
def status():
while 1:
coro.sleep_relative (2)
coro.write_stderr ('%5d worms %5d threads\n' % (len(the_arena.worms), len(coro.all_threads)))
def serve():
s = coro.tcp_sock()
s.bind (('', 9001))
s.listen (5)
while 1:
c, a = s.accept()
t = terminal (c)
the_arena.listeners.append (t)
if __name__ == '__main__':
import coro.backdoor
the_arena = arena()
the_arena.populate (10)
coro.spawn (status)
coro.spawn (serve)
coro.spawn (coro.backdoor.serve, unix_path='/tmp/xx.bd')
#import coro.profiler
#coro.profiler.go (coro.event_loop)
coro.event_loop()
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7