[ViewVC] Annotation 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 (17 years, 3 months ago) by root
Branch:	MAIN
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.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