ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libeio/eio.pod
(Generate patch)

Comparing libeio/eio.pod (file contents):
Revision 1.7 by root, Sun Jun 5 22:44:30 2011 UTC vs.
Revision 1.8 by root, Sun Jun 5 22:45:49 2011 UTC

… …
137C<want_poll> you would write a single byte, in C<done_poll> you would try 137C<want_poll> you would write a single byte, in C<done_poll> you would try
138to read that byte, and in the callback for the read end, you would call 138to read that byte, and in the callback for the read end, you would call
139C<eio_poll>. The race is avoided here because the event loop should invoke 139C<eio_poll>. The race is avoided here because the event loop should invoke
140your callback again and again until the byte has been read (as the pipe 140your callback again and again until the byte has been read (as the pipe
141read callback does not read it, only C<done_poll>). 141read callback does not read it, only C<done_poll>).
142
143=head2 CONFIGURATION
144
145The functions in this section can sometimes be useful, but the default
146configuration will do in most case, so you should skip this section on
147first reading.
148
149=over 4
150
151=item eio_set_max_poll_time (eio_tstamp nseconds)
152
153This causes C<eio_poll ()> to return after it has detected that it was
154running for C<nsecond> seconds or longer (this number can be fractional).
155
156This can be used to limit the amount of time spent handling eio requests,
157for example, in interactive programs, you might want to limit this time to
158C<0.01> seconds or so.
159
160Note that:
161
162a) libeio doesn't know how long your request callbacks take, so the time
163spent in C<eio_poll> is up to one callback invocation longer then this
164interval.
165
166b) this is implemented by calling C<gettimeofday> after each request,
167which can be costly.
168
169c) at least one request will be handled.
170
171=item eio_set_max_poll_reqs (unsigned int nreqs)
172
173When C<nreqs> is non-zero, then C<eio_poll> will not handle more than
174C<nreqs> requests per invocation. This is a less costly way to limit the
175amount of work done by C<eio_poll> then setting a time limit.
176
177If you know your callbacks are generally fast, you could use this to
178encourage interactiveness in your programs by setting it to C<10>, C<100>
179or even C<1000>.
180
181=item eio_set_min_parallel (unsigned int nthreads)
182
183Make sure libeio can handle at least this many requests in parallel. It
184might be able handle more.
185
186=item eio_set_max_parallel (unsigned int nthreads)
187
188Set the maximum number of threads that libeio will spawn.
189
190=item eio_set_max_idle (unsigned int nthreads)
191
192Libeio uses threads internally to handle most requests, and will start and stop threads on demand.
193
194This call can be used to limit the number of idle threads (threads without
195work to do): libeio will keep some threads idle in preparation for more
196requests, but never longer than C<nthreads> threads.
197
198In addition to this, libeio will also stop threads when they are idle for
199a few seconds, regardless of this setting.
200
201=item unsigned int eio_nthreads ()
202
203Return the number of worker threads currently running.
204
205=item unsigned int eio_nreqs ()
206
207Return the number of requests currently handled by libeio. This is the
208total number of requests that have been submitted to libeio, but not yet
209destroyed.
210
211=item unsigned int eio_nready ()
212
213Returns the number of ready requests, i.e. requests that have been
214submitted but have not yet entered the execution phase.
215
216=item unsigned int eio_npending ()
217
218Returns the number of pending requests, i.e. requests that have been
219executed and have results, but have not been finished yet by a call to
220C<eio_poll>).
221
222=back
223 142
224 143
225=head1 HIGH LEVEL REQUEST API 144=head1 HIGH LEVEL REQUEST API
226 145
227Libeio has both a high-level API, which consists of calling a request 146Libeio has both a high-level API, which consists of calling a request
… …
660 579
661zero 580zero
662 581
663#TODO 582#TODO
664 583
584=head2 CONFIGURATION
585
586The functions in this section can sometimes be useful, but the default
587configuration will do in most case, so you should skip this section on
588first reading.
589
590=over 4
591
592=item eio_set_max_poll_time (eio_tstamp nseconds)
593
594This causes C<eio_poll ()> to return after it has detected that it was
595running for C<nsecond> seconds or longer (this number can be fractional).
596
597This can be used to limit the amount of time spent handling eio requests,
598for example, in interactive programs, you might want to limit this time to
599C<0.01> seconds or so.
600
601Note that:
602
603a) libeio doesn't know how long your request callbacks take, so the time
604spent in C<eio_poll> is up to one callback invocation longer then this
605interval.
606
607b) this is implemented by calling C<gettimeofday> after each request,
608which can be costly.
609
610c) at least one request will be handled.
611
612=item eio_set_max_poll_reqs (unsigned int nreqs)
613
614When C<nreqs> is non-zero, then C<eio_poll> will not handle more than
615C<nreqs> requests per invocation. This is a less costly way to limit the
616amount of work done by C<eio_poll> then setting a time limit.
617
618If you know your callbacks are generally fast, you could use this to
619encourage interactiveness in your programs by setting it to C<10>, C<100>
620or even C<1000>.
621
622=item eio_set_min_parallel (unsigned int nthreads)
623
624Make sure libeio can handle at least this many requests in parallel. It
625might be able handle more.
626
627=item eio_set_max_parallel (unsigned int nthreads)
628
629Set the maximum number of threads that libeio will spawn.
630
631=item eio_set_max_idle (unsigned int nthreads)
632
633Libeio uses threads internally to handle most requests, and will start and stop threads on demand.
634
635This call can be used to limit the number of idle threads (threads without
636work to do): libeio will keep some threads idle in preparation for more
637requests, but never longer than C<nthreads> threads.
638
639In addition to this, libeio will also stop threads when they are idle for
640a few seconds, regardless of this setting.
641
642=item unsigned int eio_nthreads ()
643
644Return the number of worker threads currently running.
645
646=item unsigned int eio_nreqs ()
647
648Return the number of requests currently handled by libeio. This is the
649total number of requests that have been submitted to libeio, but not yet
650destroyed.
651
652=item unsigned int eio_nready ()
653
654Returns the number of ready requests, i.e. requests that have been
655submitted but have not yet entered the execution phase.
656
657=item unsigned int eio_npending ()
658
659Returns the number of pending requests, i.e. requests that have been
660executed and have results, but have not been finished yet by a call to
661C<eio_poll>).
662
663=back
664
665=head1 EMBEDDING 665=head1 EMBEDDING
666 666
667Libeio can be embedded directly into programs. This functionality is not 667Libeio can be embedded directly into programs. This functionality is not
668documented and not (yet) officially supported. 668documented and not (yet) officially supported.
669 669

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines