/usr/lib/swi-prolog/doc/Manual/threadpool.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.11.18 Reference Manual: Section A.24</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="simplex.html">
<LINK REL=next HREF="ugraphs.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

dt.multidef
{ background-color: #c8ffc7;
}

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="simplex.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="ugraphs.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:A.24"><SPAN class="sec-nr">A.24</SPAN> <SPAN class="sec-title">library(thread_pool): 
Resource bounded thread management</SPAN></A></H2>

<P><A NAME="sec:threadpool"></A>

<DL>
<DT><B>See also</B><DD>
<SPAN class="pred-ext">http_handler/3</SPAN> and <SPAN class="pred-ext">http_spawn/2</SPAN>.
</DL>

<P>The module library(thread_pool) manages threads in pools. A pool 
defines properties of its member threads and the maximum number of 
threads that can coexist in the pool. The call <A class="pred" href="threadpool.html#thread_create_in_pool/4">thread_create_in_pool/4</A> 
allocates a thread in the pool, just like <A class="pred" href="threadcreate.html#thread_create/3">thread_create/3</A>. 
If the pool is fully allocated it can be asked to wait or raise an 
error.

<P>The library has been designed to deal with server application that 
recieve a variety of requests, such as HTTP servers. Simply starting a 
thread for each request is a bit too simple minded for such servers:

<P>
<UL class="latex">
<LI>Creating many CPU intensive threads often leads to a slow-down 
rather than a speedup.
<LI>Creating many memory intensive threads may exhaust resources
<LI>Tasks that require little CPU and memory but take long waiting for 
external resources can run many threads.
</UL>

<P>Using this library, one can define a pool for each set of tasks with 
comparable characteristics and create threads in this pool. Unlike the 
worker-pool model, threads are not started immediately. Depending on the 
design, both approaches can be attractive.

<P>The library is implemented by means of a manager thread with the 
fixed thread id <CODE>__thread_pool_manager</CODE>. All state is 
maintained in this manager thread, which receives and processes requests 
to create and destroy pools, create threads in a pool and handle 
messages from terminated threads. Thread pools are <I>not</I> saved in a 
saved state and must therefore be recreated using the <A class="pred" href="consulting.html#initialization/1">initialization/1</A> 
directive or otherwise during startup of the application.

<DL class="latex">
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="thread_pool_create/3"><STRONG>thread_pool_create</STRONG>(<VAR>+Pool, 
+Size, +Options</VAR>)</A></DT>
<DD class="defbody">
Create a pool of threads. A pool of threads is a declaration for 
creating threads with shared properties (stack sizes) and a limited 
number of threads. Threads are created using
<A class="pred" href="threadpool.html#thread_create_in_pool/4">thread_create_in_pool/4</A>. 
If all threads in the pool are in use, the behaviour depends on the <CODE>wait</CODE> 
option of
<A class="pred" href="threadpool.html#thread_create_in_pool/4">thread_create_in_pool/4</A> 
and the <CODE>backlog</CODE> option described below. <VAR>Options</VAR> 
are passed to <A class="pred" href="threadcreate.html#thread_create/3">thread_create/3</A>, 
except for

<DL class="latex">
<DT><STRONG>backlog</STRONG>(<VAR>+MaxBackLog</VAR>)</DT>
<DD class="defbody">
Maximum number of requests that can be suspended. Default is <CODE>infinite</CODE>. 
Otherwise it must be a non-negative integer. Using backlog(0) will never 
delay thread creation for this pool.
</DD>
</DL>

<P>The pooling mechanism does <I>not</I> interact with the <CODE>detached</CODE> 
state of a thread. Threads can be created both <CODE>detached</CODE> and 
normal and must be joined using <A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A> 
if they are not detached.

<DL>
<DT><B>bug</B><DD> The thread creation option <CODE>at_exit</CODE> is 
reserved for internal use by this library.
</DL>

</DD>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="thread_pool_destroy/1"><STRONG>thread_pool_destroy</STRONG>(<VAR>+Name</VAR>)</A></DT>
<DD class="defbody">
Destroy the thread pool named <VAR>Name</VAR>.

<DL>
<DT><B>Errors</B><DD> existence_error(thread_pool, <VAR>Name</VAR>).
</DL>

</DD>
<DT class="pubdef"><span class="pred-tag">[nondet]</span><A NAME="current_thread_pool/1"><STRONG>current_thread_pool</STRONG>(<VAR>?Name</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Name</VAR> refers to a defined thread pool.</DD>
<DT class="pubdef"><span class="pred-tag">[nondet]</span><A NAME="thread_pool_property/2"><STRONG>thread_pool_property</STRONG>(<VAR>?Name, 
?Property</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Property</VAR> is a property of thread pool <VAR>Name</VAR>. 
Defined properties are:

<DL class="latex">
<DT><STRONG>options</STRONG>(<VAR>Options</VAR>)</DT>
<DD class="defbody">
Thread creation options for this pool
</DD>
<DT><STRONG>free</STRONG>(<VAR>Size</VAR>)</DT>
<DD class="defbody">
Number of free slots on this pool
</DD>
<DT><STRONG>size</STRONG>(<VAR>Size</VAR>)</DT>
<DD class="defbody">
Total number of slots on this pool
</DD>
<DT><STRONG>members</STRONG>(<VAR>ListOfIDs</VAR>)</DT>
<DD class="defbody">
ListOfIDs is the list or threads running in this pool
</DD>
<DT><STRONG>running</STRONG>(<VAR>Running</VAR>)</DT>
<DD class="defbody">
Number of running threads in this pool
</DD>
<DT><STRONG>backlog</STRONG>(<VAR>Size</VAR>)</DT>
<DD class="defbody">
Number of delayed thread creations on this pool
</DD>
</DL>

</DD>
<DT class="pubdef"><span class="pred-tag">[det]</span><A NAME="thread_create_in_pool/4"><STRONG>thread_create_in_pool</STRONG>(<VAR>+Pool, 
:Goal, -Id, +Options</VAR>)</A></DT>
<DD class="defbody">
Create a thread in <VAR>Pool</VAR>. <VAR>Options</VAR> overrule default 
thread creation options associated to the pool. In addition, the 
following option is defined:

<DL class="latex">
<DT><STRONG>wait</STRONG>(<VAR>+Boolean</VAR>)</DT>
<DD class="defbody">
If <CODE>true</CODE> (default) and the pool is full, wait until a member 
of the pool completes. If <CODE>false</CODE>, throw a resource_error.
</DD>
</DL>

<DL>
<DT><B>Errors</B><DD>- resource_error(threads_in_pool(<VAR>Pool</VAR>)) 
is raised if wait is <CODE>false</CODE> or the backlog limit has been 
reached. <BR>
- existence_error(thread_pool, <VAR>Pool</VAR>) if <VAR>Pool</VAR> does 
not exist.
</DL>

</DD>
</DL>

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / threadpool.html
