README.html 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356
  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  3. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  4. <html xmlns="http://www.w3.org/1999/xhtml"
  5. lang="en" xml:lang="en">
  6. <head>
  7. <title>README</title>
  8. <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
  9. <meta name="generator" content="Org-mode"/>
  10. <meta name="generated" content="2010-09-05 17:17:09 PDT"/>
  11. <meta name="author" content="Seth Falcon"/>
  12. <meta name="description" content=""/>
  13. <meta name="keywords" content=""/>
  14. <style type="text/css">
  15. <!--/*--><![CDATA[/*><!--*/
  16. html { font-family: Times, serif; font-size: 12pt; }
  17. .title { text-align: center; }
  18. .todo { color: red; }
  19. .done { color: green; }
  20. .tag { background-color: #add8e6; font-weight:normal }
  21. .target { }
  22. .timestamp { color: #bebebe; }
  23. .timestamp-kwd { color: #5f9ea0; }
  24. p.verse { margin-left: 3% }
  25. pre {
  26. border: 1pt solid #AEBDCC;
  27. background-color: #F3F5F7;
  28. padding: 5pt;
  29. font-family: courier, monospace;
  30. font-size: 90%;
  31. overflow:auto;
  32. }
  33. table { border-collapse: collapse; }
  34. td, th { vertical-align: top; }
  35. dt { font-weight: bold; }
  36. div.figure { padding: 0.5em; }
  37. div.figure p { text-align: center; }
  38. textarea { overflow-x: auto; }
  39. .linenr { font-size:smaller }
  40. .code-highlighted {background-color:#ffff00;}
  41. .org-info-js_info-navigation { border-style:none; }
  42. #org-info-js_console-label { font-size:10px; font-weight:bold;
  43. white-space:nowrap; }
  44. .org-info-js_search-highlight {background-color:#ffff00; color:#000000;
  45. font-weight:bold; }
  46. /*]]>*/-->
  47. </style>
  48. <script type="text/javascript">
  49. <!--/*--><![CDATA[/*><!--*/
  50. function CodeHighlightOn(elem, id)
  51. {
  52. var target = document.getElementById(id);
  53. if(null != target) {
  54. elem.cacheClassElem = elem.className;
  55. elem.cacheClassTarget = target.className;
  56. target.className = "code-highlighted";
  57. elem.className = "code-highlighted";
  58. }
  59. }
  60. function CodeHighlightOff(elem, id)
  61. {
  62. var target = document.getElementById(id);
  63. if(elem.cacheClassElem)
  64. elem.className = elem.cacheClassElem;
  65. if(elem.cacheClassTarget)
  66. target.className = elem.cacheClassTarget;
  67. }
  68. /*]]>*///-->
  69. </script>
  70. </head>
  71. <body>
  72. <div id="content">
  73. <h1 class="title">README</h1>
  74. <div id="table-of-contents">
  75. <h2>Table of Contents</h2>
  76. <div id="text-table-of-contents">
  77. <ul>
  78. <li><a href="#sec-1">1 pidq - A Process Pool Library for Erlang </a>
  79. <ul>
  80. <li><a href="#sec-1_1">1.1 Use pidq to manage pools of processes (pids). </a></li>
  81. <li><a href="#sec-1_2">1.2 Motivation </a></li>
  82. <li><a href="#sec-1_3">1.3 Usage and API </a>
  83. <ul>
  84. <li><a href="#sec-1_3_1">1.3.1 Startup configuration </a></li>
  85. <li><a href="#sec-1_3_2">1.3.2 Getting and returning pids </a></li>
  86. <li><a href="#sec-1_3_3">1.3.3 Other things you can do </a></li>
  87. </ul>
  88. </li>
  89. <li><a href="#sec-1_4">1.4 Details </a></li>
  90. </ul>
  91. </li>
  92. </ul>
  93. </div>
  94. </div>
  95. <div id="outline-container-1" class="outline-2">
  96. <h2 id="sec-1"><span class="section-number-2">1</span> pidq - A Process Pool Library for Erlang </h2>
  97. <div class="outline-text-2" id="text-1">
  98. </div>
  99. <div id="outline-container-1_1" class="outline-3">
  100. <h3 id="sec-1_1"><span class="section-number-3">1.1</span> Use pidq to manage pools of processes (pids). </h3>
  101. <div class="outline-text-3" id="text-1_1">
  102. <ul>
  103. <li>
  104. Protect the pids from being used concurrently. The main pidq
  105. interface is <code>pidq:take_pid/0</code> and <code>pidq:return_pid/2</code>. The pidq
  106. server will keep track of which pids are <b>in use</b> and which are
  107. <b>free</b>.
  108. </li>
  109. <li>
  110. Maintain the size of the pid pool. Specify a maximum number of pids
  111. in the pool. Trigger pid creation when the free count drops below a
  112. minimum level or when a pid is marked as failing.
  113. </li>
  114. <li>
  115. Organize pids by type and randomly load-balance pids by type. This
  116. is useful when the pids represent client processes connected to a
  117. particular node in a cluster (think database read slaves). Separate
  118. pools are maintained for each type and a request for a pid will
  119. randomly select a type.
  120. </li>
  121. </ul>
  122. </div>
  123. </div>
  124. <div id="outline-container-1_2" class="outline-3">
  125. <h3 id="sec-1_2"><span class="section-number-3">1.2</span> Motivation </h3>
  126. <div class="outline-text-3" id="text-1_2">
  127. <p>
  128. The need for the pidq kit arose while writing an Erlang-based
  129. application that uses <a href="https://wiki.basho.com/display/RIAK/">Riak</a> for data storage. When using the Erlang
  130. protocol buffer client for Riak, one should avoid accessing a given
  131. client concurrently. This is because each client is associated with a
  132. unique client ID that corresponds to an element in an object's vector
  133. clock. Concurrent action from the same client ID defeats the vector
  134. clock. For some further explaination, see <sup><a class="footref" name="fnr.1" href="#fn.1">1</a></sup> and <sup><a class="footref" name="fnr.2" href="#fn.2">2</a></sup>.
  135. </p>
  136. <p>
  137. I wanted to avoid spinning up a new client for each request in the
  138. application. Riak's protocol buffer client is a <code>gen_server</code> process
  139. and my intuition is that one doesn't want to pay for the startup time
  140. for every request you send to an app. This suggested a pool of
  141. clients with some management to avoid concurrent use of a given
  142. client. On top of that, it seemed convenient to add the ability to
  143. load balance between clients connected to different nodes in the Riak
  144. cluster. The load-balancing is a secondary feature; even if you end
  145. up setting up <a href="http://haproxy.1wt.eu/">HAProxy</a> for that aspect, you might still want the client
  146. pooling.
  147. </p>
  148. </div>
  149. </div>
  150. <div id="outline-container-1_3" class="outline-3">
  151. <h3 id="sec-1_3"><span class="section-number-3">1.3</span> Usage and API </h3>
  152. <div class="outline-text-3" id="text-1_3">
  153. </div>
  154. <div id="outline-container-1_3_1" class="outline-4">
  155. <h4 id="sec-1_3_1"><span class="section-number-4">1.3.1</span> Startup configuration </h4>
  156. <div class="outline-text-4" id="text-1_3_1">
  157. <p>
  158. The idea is that you would wire up pidq to be a supervised process in
  159. your application. When you start pidq, you specify a module and
  160. function to use for creating new pids. You also specify the
  161. properties for each pool that you want pidq to manage, including the
  162. arguments to pass to the pid starter function.
  163. </p>
  164. <p>
  165. An example configuration looks like this:
  166. </p>
  167. <pre class="src src-erlang"><span style="color: #FF6400;">Pool1</span> = [{<span style="color: #D8FA3C;">name</span>, <span style="color: #61CE3C;">"node1"</span>},
  168. {<span style="color: #D8FA3C;">max_pids</span>, 10},
  169. {<span style="color: #D8FA3C;">min_free</span>, 2},
  170. {<span style="color: #D8FA3C;">init_size</span>, 5}
  171. {<span style="color: #D8FA3C;">pid_starter_args</span>, <span style="color: #FF6400;">Args1</span>}],
  172. <span style="color: #FF6400;">Pool2</span> = [{<span style="color: #D8FA3C;">name</span>, <span style="color: #61CE3C;">"node2"</span>},
  173. {<span style="color: #D8FA3C;">max_pids</span>, 100},
  174. {<span style="color: #D8FA3C;">min_free</span>, 2},
  175. {<span style="color: #D8FA3C;">init_size</span>, 50}
  176. {<span style="color: #D8FA3C;">pid_starter_args</span>, <span style="color: #FF6400;">Args2</span>}],
  177. <span style="color: #FF6400;">Config</span> = [{<span style="color: #D8FA3C;">pid_starter</span>, {<span style="color: #FF6400;">M</span>, <span style="color: #FF6400;">F</span>}},
  178. {<span style="color: #D8FA3C;">pid_stopper</span>, {<span style="color: #FF6400;">M</span>, <span style="color: #FF6400;">F</span>}},
  179. {<span style="color: #D8FA3C;">pools</span>, [<span style="color: #FF6400;">Pool1</span>, <span style="color: #FF6400;">Pool2</span>]}]
  180. <span style="color: #AEAEAE; font-style: italic;">% </span><span style="color: #AEAEAE; font-style: italic;">either call this directly, or wire this
  181. </span><span style="color: #AEAEAE; font-style: italic;">% </span><span style="color: #AEAEAE; font-style: italic;">call into your application's supervisor
  182. </span><span style="color: #8DA6CE;">pidq</span>:<span style="color: #8DA6CE;">start</span>(<span style="color: #FF6400;">Config</span>)
  183. </pre>
  184. <p>
  185. Each pool has a unique name, a maximum number of pids, an initial
  186. number of pids, and a minimum free pids count. When pidq starts, it
  187. will create pids to match the <code>init_size</code> value. If there are <code>min_free</code>
  188. pids or fewer, pidq will add a pid as long as that doesn't bring the
  189. total used + free count over <code>max_pids</code>.
  190. </p>
  191. <p>
  192. Specifying a <code>pid_stopper</code> function is optional. If not specified,
  193. <code>exit(pid, kill)</code> will be used to shutdown pids in the case of error,
  194. pidq shutdown, or pool removal. The function specified will be passed
  195. a pid as returned by the <code>pid_starter</code> function.
  196. </p>
  197. </div>
  198. </div>
  199. <div id="outline-container-1_3_2" class="outline-4">
  200. <h4 id="sec-1_3_2"><span class="section-number-4">1.3.2</span> Getting and returning pids </h4>
  201. <div class="outline-text-4" id="text-1_3_2">
  202. <p>
  203. Once started, the main interaction you will have with pidq is through
  204. two functions, <code>take_pid/0</code> and <code>return_pid/2</code>.
  205. </p>
  206. <p>
  207. Call <code>pidq:take_pid()</code> to obtain a pid from the pool. When you are done
  208. with it, return it to the pool using <code>pidq:return_pid(Pid, ok)</code>. If
  209. you encountered an error using the pid, you can pass <code>fail</code> as the
  210. second argument. In this case, pidq will permently remove that pid
  211. from the pool and start a new pid to replace it.
  212. </p>
  213. </div>
  214. </div>
  215. <div id="outline-container-1_3_3" class="outline-4">
  216. <h4 id="sec-1_3_3"><span class="section-number-4">1.3.3</span> Other things you can do </h4>
  217. <div class="outline-text-4" id="text-1_3_3">
  218. <p>
  219. You can get the status for the system via <code>pidq:status()</code>. This will
  220. return some informational details about the pools being managed.
  221. </p>
  222. <p>
  223. You can also add or remove new pools while pidq is running using
  224. <code>pidq:add_pool/1</code> and <code>pidq:remove_pool/1</code>. Each pid
  225. </p>
  226. </div>
  227. </div>
  228. </div>
  229. <div id="outline-container-1_4" class="outline-3">
  230. <h3 id="sec-1_4"><span class="section-number-3">1.4</span> Details </h3>
  231. <div class="outline-text-3" id="text-1_4">
  232. <p>
  233. pidq is implemented as a <code>gen_server</code>. Server state consists of a dict
  234. of pools keyed by pool name. Each pool keeps track of its parameters,
  235. a free list, and an in-use list. Since our motivating use-case is
  236. Riak's pb client, we opt to reuse a given client as much as possible
  237. to avoid unnecessary vector clock growth. So pids are taken from the
  238. head of the free list and returned to the head of the free list.
  239. </p>
  240. <p>
  241. It is an error to add a pool with a name that already exists.
  242. </p>
  243. <p>
  244. Pool removal has two forms:
  245. </p>
  246. <ul>
  247. <li>
  248. <b>graceful</b> pids in the free list are killed (using exit(pid, kill)
  249. unless a <code>pid_stopper</code> is specified in the pool parameters. No pids
  250. will be handed out from this pool's free list. As pids are
  251. returned, they are shut down. When the pool is empty, it is
  252. removed.
  253. </li>
  254. <li>
  255. <b>immediate</b> all pids in free and in-use lists are shut down; the
  256. pool is removed.
  257. </li>
  258. </ul>
  259. <pre class="src src-erlang"><span style="color: #7fffd4;">-spec</span>(<span style="color: #8DA6CE;">take_pid</span>() -&gt; <span style="color: #94bff3;">pid</span>()).
  260. <span style="color: #7fffd4;">-spec</span>(<span style="color: #8DA6CE;">return_pid</span>(<span style="color: #94bff3;">pid</span>(), <span style="color: #D8FA3C;">ok</span> | <span style="color: #D8FA3C;">fail</span>) -&gt; <span style="color: #D8FA3C;">ignore</span>).
  261. <span style="color: #7fffd4;">-spec</span>(<span style="color: #8DA6CE;">status</span>() -&gt; [<span style="color: #8DA6CE;">term</span>()]).
  262. <span style="color: #7fffd4;">-type</span>(<span style="color: #8DA6CE;">pid_type_opt</span>() ::
  263. {<span style="color: #D8FA3C;">name</span>, <span style="color: #8DA6CE;">string</span>()} |
  264. {<span style="color: #D8FA3C;">max_pids</span>, <span style="color: #8DA6CE;">int</span>()} |
  265. {<span style="color: #D8FA3C;">min_free</span>, <span style="color: #8DA6CE;">int</span>()} |
  266. {<span style="color: #D8FA3C;">init_size</span>, <span style="color: #8DA6CE;">int</span>()} |
  267. {<span style="color: #D8FA3C;">pid_starter_args</span>, [<span style="color: #8DA6CE;">term</span>()]}).
  268. <span style="color: #7fffd4;">-type</span>(<span style="color: #8DA6CE;">pid_type_spec</span>() :: [<span style="color: #8DA6CE;">pid_type_opt</span>()]).
  269. <span style="color: #7fffd4;">-spec</span>(<span style="color: #8DA6CE;">add_type</span>(<span style="color: #8DA6CE;">pid_type_spec</span>()) -&gt; <span style="color: #D8FA3C;">ok</span> | {<span style="color: #D8FA3C;">error</span>, <span style="color: #FF6400;">Why</span>}).
  270. <span style="color: #7fffd4;">-spec</span>(<span style="color: #8DA6CE;">remove_type</span>(<span style="color: #8DA6CE;">string</span>()) -&gt; <span style="color: #D8FA3C;">ok</span> | {<span style="color: #D8FA3C;">error</span>, <span style="color: #FF6400;">Why</span>}).
  271. </pre>
  272. </div>
  273. </div>
  274. </div>
  275. <div id="footnotes">
  276. <h2 class="footnotes">Footnotes: </h2>
  277. <div id="text-footnotes">
  278. <p class="footnote"><sup><a class="footnum" name="fn.1" href="#fnr.1">1</a></sup> <a href="http://lists.basho.com/pipermail/riak-users_lists.basho.com/2010-September/001900.html">http://lists.basho.com/pipermail/riak-users_lists.basho.com/2010-September/001900.html</a>
  279. </p>
  280. <p class="footnote"><sup><a class="footnum" name="fn.2" href="#fnr.2">2</a></sup> <a href="http://lists.basho.com/pipermail/riak-users_lists.basho.com/2010-September/001904.html">http://lists.basho.com/pipermail/riak-users_lists.basho.com/2010-September/001904.html</a>
  281. </p>
  282. </div>
  283. </div>
  284. <div id="postamble">
  285. <p class="author"> Author: Seth Falcon
  286. </p>
  287. <p class="date"> Date: 2010-09-05 17:17:09 PDT</p>
  288. <p class="creator">HTML generated by org-mode 7.01trans in emacs 23</p>
  289. </div>
  290. </div>
  291. </body>
  292. </html>