[ViewVC] Contents of: cvs/BDB/README

NAME
    BDB::AIO - Asynchronous Berkeley DB access

SYNOPSIS
     use BDB::AIO;

DESCRIPTION
  EXAMPLE
REQUEST ANATOMY AND LIFETIME
    Every request method creates a request. which is a C data structure not
    directly visible to Perl.

    During their existance, bdb requests travel through the following
    states, in order:

    ready
        Immediately after a request is created it is put into the ready
        state, waiting for a thread to execute it.

    execute
        A thread has accepted the request for processing and is currently
        executing it (e.g. blocking in read).

    pending
        The request has been executed and is waiting for result processing.

        While request submission and execution is fully asynchronous, result
        processing is not and relies on the perl interpreter calling
        "poll_cb" (or another function with the same effect).

    result
        The request results are processed synchronously by "poll_cb".

        The "poll_cb" function will process all outstanding aio requests by
        calling their callbacks, freeing memory associated with them and
        managing any groups they are contained in.

    done
        Request has reached the end of its lifetime and holds no resources
        anymore (except possibly for the Perl object, but its connection to
        the actual aio request is severed and calling its methods will
        either do nothing or result in a runtime error).

  SUPPORT FUNCTIONS
   EVENT PROCESSING AND EVENT LOOP INTEGRATION
    $fileno = BDB::AIO::poll_fileno
        Return the *request result pipe file descriptor*. This filehandle
        must be polled for reading by some mechanism outside this module
        (e.g. Event or select, see below or the SYNOPSIS). If the pipe
        becomes readable you have to call "poll_cb" to check the results.

        See "poll_cb" for an example.

    BDB::AIO::poll_cb
        Process some outstanding events on the result pipe. You have to call
        this regularly. Returns the number of events processed. Returns
        immediately when no events are outstanding. The amount of events
        processed depends on the settings of "BDB::AIO::max_poll_req" and
        "BDB::AIO::max_poll_time".

        If not all requests were processed for whatever reason, the
        filehandle will still be ready when "poll_cb" returns.

        Example: Install an Event watcher that automatically calls
        BDB::AIO::poll_cb with high priority:

           Event->io (fd => BDB::AIO::poll_fileno,
                      poll => 'r', async => 1,
                      cb => \&BDB::AIO::poll_cb);

    BDB::AIO::max_poll_reqs $nreqs
    BDB::AIO::max_poll_time $seconds
        These set the maximum number of requests (default 0, meaning
        infinity) that are being processed by "BDB::AIO::poll_cb" in one
        call, respectively the maximum amount of time (default 0, meaning
        infinity) spent in "BDB::AIO::poll_cb" to process requests (more
        correctly the mininum amount of time "poll_cb" is allowed to use).

        Setting "max_poll_time" to a non-zero value creates an overhead of
        one syscall per request processed, which is not normally a problem
        unless your callbacks are really really fast or your OS is really
        really slow (I am not mentioning Solaris here). Using
        "max_poll_reqs" incurs no overhead.

        Setting these is useful if you want to ensure some level of
        interactiveness when perl is not fast enough to process all requests
        in time.

        For interactive programs, values such as 0.01 to 0.1 should be fine.

        Example: Install an Event watcher that automatically calls
        BDB::AIO::poll_cb with low priority, to ensure that other parts of
        the program get the CPU sometimes even under high AIO load.

           # try not to spend much more than 0.1s in poll_cb
           BDB::AIO::max_poll_time 0.1;

           # use a low priority so other tasks have priority
           Event->io (fd => BDB::AIO::poll_fileno,
                      poll => 'r', nice => 1,
                      cb => &BDB::AIO::poll_cb);

    BDB::AIO::poll_wait
        If there are any outstanding requests and none of them in the result
        phase, wait till the result filehandle becomes ready for reading
        (simply does a "select" on the filehandle. This is useful if you
        want to synchronously wait for some requests to finish).

        See "nreqs" for an example.

    BDB::AIO::poll
        Waits until some requests have been handled.

        Returns the number of requests processed, but is otherwise strictly
        equivalent to:

           BDB::AIO::poll_wait, BDB::AIO::poll_cb

    BDB::AIO::flush
        Wait till all outstanding AIO requests have been handled.

        Strictly equivalent to:

           BDB::AIO::poll_wait, BDB::AIO::poll_cb
              while BDB::AIO::nreqs;

   CONTROLLING THE NUMBER OF THREADS
    BDB::AIO::min_parallel $nthreads
        Set the minimum number of AIO threads to $nthreads. The current
        default is 8, which means eight asynchronous operations can execute
        concurrently at any one time (the number of outstanding requests,
        however, is unlimited).

        BDB::AIO starts threads only on demand, when an AIO request is
        queued and no free thread exists. Please note that queueing up a
        hundred requests can create demand for a hundred threads, even if it
        turns out that everything is in the cache and could have been
        processed faster by a single thread.

        It is recommended to keep the number of threads relatively low, as
        some Linux kernel versions will scale negatively with the number of
        threads (higher parallelity => MUCH higher latency). With current
        Linux 2.6 versions, 4-32 threads should be fine.

        Under most circumstances you don't need to call this function, as
        the module selects a default that is suitable for low to moderate
        load.

    BDB::AIO::max_parallel $nthreads
        Sets the maximum number of AIO threads to $nthreads. If more than
        the specified number of threads are currently running, this function
        kills them. This function blocks until the limit is reached.

        While $nthreads are zero, aio requests get queued but not executed
        until the number of threads has been increased again.

        This module automatically runs "max_parallel 0" at program end, to
        ensure that all threads are killed and that there are no outstanding
        requests.

        Under normal circumstances you don't need to call this function.

    BDB::AIO::max_idle $nthreads
        Limit the number of threads (default: 4) that are allowed to idle
        (i.e., threads that did not get a request to process within 10
        seconds). That means if a thread becomes idle while $nthreads other
        threads are also idle, it will free its resources and exit.

        This is useful when you allow a large number of threads (e.g. 100 or
        1000) to allow for extremely high load situations, but want to free
        resources under normal circumstances (1000 threads can easily
        consume 30MB of RAM).

        The default is probably ok in most situations, especially if thread
        creation is fast. If thread creation is very slow on your system you
        might want to use larger values.

    $oldmaxreqs = BDB::AIO::max_outstanding $maxreqs
        This is a very bad function to use in interactive programs because
        it blocks, and a bad way to reduce concurrency because it is
        inexact: Better use an "aio_group" together with a feed callback.

        Sets the maximum number of outstanding requests to $nreqs. If you to
        queue up more than this number of requests, the next call to the
        "poll_cb" (and "poll_some" and other functions calling "poll_cb")
        function will block until the limit is no longer exceeded.

        The default value is very large, so there is no practical limit on
        the number of outstanding requests.

        You can still queue as many requests as you want. Therefore,
        "max_oustsanding" is mainly useful in simple scripts (with low
        values) or as a stop gap to shield against fatal memory overflow
        (with large values).

   STATISTICAL INFORMATION
    BDB::AIO::nreqs
        Returns the number of requests currently in the ready, execute or
        pending states (i.e. for which their callback has not been invoked
        yet).

        Example: wait till there are no outstanding requests anymore:

           BDB::AIO::poll_wait, BDB::AIO::poll_cb
              while BDB::AIO::nreqs;

    BDB::AIO::nready
        Returns the number of requests currently in the ready state (not yet
        executed).

    BDB::AIO::npending
        Returns the number of requests currently in the pending state
        (executed, but not yet processed by poll_cb).

  FORK BEHAVIOUR
    This module should do "the right thing" when the process using it forks:

    Before the fork, IO::AIO enters a quiescent state where no requests can
    be added in other threads and no results will be processed. After the
    fork the parent simply leaves the quiescent state and continues
    request/result processing, while the child frees the request/result
    queue (so that the requests started before the fork will only be handled
    in the parent). Threads will be started on demand until the limit set in
    the parent process has been reached again.

    In short: the parent will, after a short pause, continue as if fork had
    not been called, while the child will act as if IO::AIO has not been
    used yet.

  MEMORY USAGE
    Per-request usage:

    Each aio request uses - depending on your architecture - around 100-200
    bytes of memory. In addition, stat requests need a stat buffer (possibly
    a few hundred bytes), readdir requires a result buffer and so on. Perl
    scalars and other data passed into aio requests will also be locked and
    will consume memory till the request has entered the done state.

    This is now awfully much, so queuing lots of requests is not usually a
    problem.

    Per-thread usage:

    In the execution phase, some aio requests require more memory for
    temporary buffers, and each thread requires a stack and other data
    structures (usually around 16k-128k, depending on the OS).

KNOWN BUGS
    Known bugs will be fixed in the next release.

SEE ALSO
    Coro::AIO.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.1
Committed:	Mon Feb 5 18:40:55 2007 UTC (19 years, 7 months ago) by root
Branch:	MAIN
Log Message:	* empty log message *
#	Content
1	NAME
2	BDB::AIO - Asynchronous Berkeley DB access
3
4	SYNOPSIS
5	use BDB::AIO;
6
7	DESCRIPTION
8	EXAMPLE
9	REQUEST ANATOMY AND LIFETIME
10	Every request method creates a request. which is a C data structure not
11	directly visible to Perl.
12
13	During their existance, bdb requests travel through the following
14	states, in order:
15
16	ready
17	Immediately after a request is created it is put into the ready
18	state, waiting for a thread to execute it.
19
20	execute
21	A thread has accepted the request for processing and is currently
22	executing it (e.g. blocking in read).
23
24	pending
25	The request has been executed and is waiting for result processing.
26
27	While request submission and execution is fully asynchronous, result
28	processing is not and relies on the perl interpreter calling
29	"poll_cb" (or another function with the same effect).
30
31	result
32	The request results are processed synchronously by "poll_cb".
33
34	The "poll_cb" function will process all outstanding aio requests by
35	calling their callbacks, freeing memory associated with them and
36	managing any groups they are contained in.
37
38	done
39	Request has reached the end of its lifetime and holds no resources
40	anymore (except possibly for the Perl object, but its connection to
41	the actual aio request is severed and calling its methods will
42	either do nothing or result in a runtime error).
43
44	SUPPORT FUNCTIONS
45	EVENT PROCESSING AND EVENT LOOP INTEGRATION
46	$fileno = BDB::AIO::poll_fileno
47	Return the request result pipe file descriptor. This filehandle
48	must be polled for reading by some mechanism outside this module
49	(e.g. Event or select, see below or the SYNOPSIS). If the pipe
50	becomes readable you have to call "poll_cb" to check the results.
51
52	See "poll_cb" for an example.
53
54	BDB::AIO::poll_cb
55	Process some outstanding events on the result pipe. You have to call
56	this regularly. Returns the number of events processed. Returns
57	immediately when no events are outstanding. The amount of events
58	processed depends on the settings of "BDB::AIO::max_poll_req" and
59	"BDB::AIO::max_poll_time".
60
61	If not all requests were processed for whatever reason, the
62	filehandle will still be ready when "poll_cb" returns.
63
64	Example: Install an Event watcher that automatically calls
65	BDB::AIO::poll_cb with high priority:
66
67	Event->io (fd => BDB::AIO::poll_fileno,
68	poll => 'r', async => 1,
69	cb => \&BDB::AIO::poll_cb);
70
71	BDB::AIO::max_poll_reqs $nreqs
72	BDB::AIO::max_poll_time $seconds
73	These set the maximum number of requests (default 0, meaning
74	infinity) that are being processed by "BDB::AIO::poll_cb" in one
75	call, respectively the maximum amount of time (default 0, meaning
76	infinity) spent in "BDB::AIO::poll_cb" to process requests (more
77	correctly the mininum amount of time "poll_cb" is allowed to use).
78
79	Setting "max_poll_time" to a non-zero value creates an overhead of
80	one syscall per request processed, which is not normally a problem
81	unless your callbacks are really really fast or your OS is really
82	really slow (I am not mentioning Solaris here). Using
83	"max_poll_reqs" incurs no overhead.
84
85	Setting these is useful if you want to ensure some level of
86	interactiveness when perl is not fast enough to process all requests
87	in time.
88
89	For interactive programs, values such as 0.01 to 0.1 should be fine.
90
91	Example: Install an Event watcher that automatically calls
92	BDB::AIO::poll_cb with low priority, to ensure that other parts of
93	the program get the CPU sometimes even under high AIO load.
94
95	# try not to spend much more than 0.1s in poll_cb
96	BDB::AIO::max_poll_time 0.1;
97
98	# use a low priority so other tasks have priority
99	Event->io (fd => BDB::AIO::poll_fileno,
100	poll => 'r', nice => 1,
101	cb => &BDB::AIO::poll_cb);
102
103	BDB::AIO::poll_wait
104	If there are any outstanding requests and none of them in the result
105	phase, wait till the result filehandle becomes ready for reading
106	(simply does a "select" on the filehandle. This is useful if you
107	want to synchronously wait for some requests to finish).
108
109	See "nreqs" for an example.
110
111	BDB::AIO::poll
112	Waits until some requests have been handled.
113
114	Returns the number of requests processed, but is otherwise strictly
115	equivalent to:
116
117	BDB::AIO::poll_wait, BDB::AIO::poll_cb
118
119	BDB::AIO::flush
120	Wait till all outstanding AIO requests have been handled.
121
122	Strictly equivalent to:
123
124	BDB::AIO::poll_wait, BDB::AIO::poll_cb
125	while BDB::AIO::nreqs;
126
127	CONTROLLING THE NUMBER OF THREADS
128	BDB::AIO::min_parallel $nthreads
129	Set the minimum number of AIO threads to $nthreads. The current
130	default is 8, which means eight asynchronous operations can execute
131	concurrently at any one time (the number of outstanding requests,
132	however, is unlimited).
133
134	BDB::AIO starts threads only on demand, when an AIO request is
135	queued and no free thread exists. Please note that queueing up a
136	hundred requests can create demand for a hundred threads, even if it
137	turns out that everything is in the cache and could have been
138	processed faster by a single thread.
139
140	It is recommended to keep the number of threads relatively low, as
141	some Linux kernel versions will scale negatively with the number of
142	threads (higher parallelity => MUCH higher latency). With current
143	Linux 2.6 versions, 4-32 threads should be fine.
144
145	Under most circumstances you don't need to call this function, as
146	the module selects a default that is suitable for low to moderate
147	load.
148
149	BDB::AIO::max_parallel $nthreads
150	Sets the maximum number of AIO threads to $nthreads. If more than
151	the specified number of threads are currently running, this function
152	kills them. This function blocks until the limit is reached.
153
154	While $nthreads are zero, aio requests get queued but not executed
155	until the number of threads has been increased again.
156
157	This module automatically runs "max_parallel 0" at program end, to
158	ensure that all threads are killed and that there are no outstanding
159	requests.
160
161	Under normal circumstances you don't need to call this function.
162
163	BDB::AIO::max_idle $nthreads
164	Limit the number of threads (default: 4) that are allowed to idle
165	(i.e., threads that did not get a request to process within 10
166	seconds). That means if a thread becomes idle while $nthreads other
167	threads are also idle, it will free its resources and exit.
168
169	This is useful when you allow a large number of threads (e.g. 100 or
170	1000) to allow for extremely high load situations, but want to free
171	resources under normal circumstances (1000 threads can easily
172	consume 30MB of RAM).
173
174	The default is probably ok in most situations, especially if thread
175	creation is fast. If thread creation is very slow on your system you
176	might want to use larger values.
177
178	$oldmaxreqs = BDB::AIO::max_outstanding $maxreqs
179	This is a very bad function to use in interactive programs because
180	it blocks, and a bad way to reduce concurrency because it is
181	inexact: Better use an "aio_group" together with a feed callback.
182
183	Sets the maximum number of outstanding requests to $nreqs. If you to
184	queue up more than this number of requests, the next call to the
185	"poll_cb" (and "poll_some" and other functions calling "poll_cb")
186	function will block until the limit is no longer exceeded.
187
188	The default value is very large, so there is no practical limit on
189	the number of outstanding requests.
190
191	You can still queue as many requests as you want. Therefore,
192	"max_oustsanding" is mainly useful in simple scripts (with low
193	values) or as a stop gap to shield against fatal memory overflow
194	(with large values).
195
196	STATISTICAL INFORMATION
197	BDB::AIO::nreqs
198	Returns the number of requests currently in the ready, execute or
199	pending states (i.e. for which their callback has not been invoked
200	yet).
201
202	Example: wait till there are no outstanding requests anymore:
203
204	BDB::AIO::poll_wait, BDB::AIO::poll_cb
205	while BDB::AIO::nreqs;
206
207	BDB::AIO::nready
208	Returns the number of requests currently in the ready state (not yet
209	executed).
210
211	BDB::AIO::npending
212	Returns the number of requests currently in the pending state
213	(executed, but not yet processed by poll_cb).
214
215	FORK BEHAVIOUR
216	This module should do "the right thing" when the process using it forks:
217
218	Before the fork, IO::AIO enters a quiescent state where no requests can
219	be added in other threads and no results will be processed. After the
220	fork the parent simply leaves the quiescent state and continues
221	request/result processing, while the child frees the request/result
222	queue (so that the requests started before the fork will only be handled
223	in the parent). Threads will be started on demand until the limit set in
224	the parent process has been reached again.
225
226	In short: the parent will, after a short pause, continue as if fork had
227	not been called, while the child will act as if IO::AIO has not been
228	used yet.
229
230	MEMORY USAGE
231	Per-request usage:
232
233	Each aio request uses - depending on your architecture - around 100-200
234	bytes of memory. In addition, stat requests need a stat buffer (possibly
235	a few hundred bytes), readdir requires a result buffer and so on. Perl
236	scalars and other data passed into aio requests will also be locked and
237	will consume memory till the request has entered the done state.
238
239	This is now awfully much, so queuing lots of requests is not usually a
240	problem.
241
242	Per-thread usage:
243
244	In the execution phase, some aio requests require more memory for
245	temporary buffers, and each thread requires a stack and other data
246	structures (usually around 16k-128k, depending on the OS).
247
248	KNOWN BUGS
249	Known bugs will be fixed in the next release.
250
251	SEE ALSO
252	Coro::AIO.
253
254	AUTHOR
255	Marc Lehmann <schmorp@schmorp.de>
256	http://home.schmorp.de/
257