ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro/State.pm
(Generate patch)

Comparing Coro/Coro/State.pm (file contents):
Revision 1.180 by root, Fri Dec 7 22:37:24 2012 UTC vs.
Revision 1.181 by root, Sat Dec 8 00:43:39 2012 UTC

… …
21 $main->transfer ($new); 21 $main->transfer ($new);
22 print "back in main\n"; 22 print "back in main\n";
23 23
24=head1 DESCRIPTION 24=head1 DESCRIPTION
25 25
26This module implements coro. Coros, similar to threads and continuations, 26This module implements coro objects. Coros, similar to threads and
27allow you to run more than one "thread of execution" in parallel. Unlike 27continuations, allow you to run more than one "thread of execution" in
28so-called "kernel" threads, there is no parallelism and only voluntary 28parallel. Unlike so-called "kernel" threads, there is no parallelism
29switching is used so locking problems are greatly reduced. The latter is 29and only voluntary switching is used so locking problems are greatly
30called "cooperative" threading as opposed to "preemptive" threading. 30reduced. The latter is called "cooperative" threading as opposed to
31"preemptive" threading.
31 32
32This can be used to implement non-local jumps, exception handling, 33This can be used to implement non-local jumps, exception handling,
33continuation objects and more. 34continuation objects and more.
34 35
35This module provides only low-level functionality. See L<Coro> and related 36This module provides only low-level functionality useful to build other
37abstractions, such as threads, generators or coroutines. See L<Coro>
36modules for a higher level threads abstraction including a scheduler. 38and related modules for a higher level threads abstraction including a
39scheduler.
37 40
38=head2 MODEL 41=head2 MODEL
39 42
40Coro::State implements two different thread models: Perl and C. The C 43Coro::State implements two different thread models: Perl and C. The C
41threads (called cctx's) are basically simplified perl interpreters 44threads (called cctx's) are basically simplified perl interpreters
… …
137 140
138Similar to above die hook, but augments C<$SIG{__WARN__}>. 141Similar to above die hook, but augments C<$SIG{__WARN__}>.
139 142
140=back 143=back
141 144
142=head2 FUNCTIONS 145=head2 Coro::State METHODS
143 146
144=over 4 147=over 4
145 148
146=item $coro = new Coro::State [$coderef[, @args...]] 149=item $coro = new Coro::State [$coderef[, @args...]]
147 150
… …
229 232
230=item $state->is_new 233=item $state->is_new
231 234
232=item $state->is_zombie 235=item $state->is_zombie
233 236
234See the corresponding method for L<Coro> objects. 237See the corresponding method(s) for L<Coro> objects.
235 238
236=item $state->cancel 239=item $state->cancel
237 240
238Forcefully destructs the given Coro::State. While you can keep the 241Forcefully destructs the given Coro::State. While you can keep the
239reference, and some memory is still allocated, the Coro::State object is 242reference, and some memory is still allocated, the Coro::State object is
… …
303You can also swap hashes and other values: 306You can also swap hashes and other values:
304 307
305 my %private_hash; 308 my %private_hash;
306 $coro->swap_sv (\%some_hash, \%private_hash); 309 $coro->swap_sv (\%some_hash, \%private_hash);
307 310
308=item $state->trace ($flags)
309
310Internal function to control tracing. I just mention this so you can stay
311away from abusing it.
312
313=item $bytes = $state->rss 311=item $bytes = $state->rss
314 312
315Returns the memory allocated by the coro (which includes static 313Returns the memory allocated by the coro (which includes static
316structures, various perl stacks but NOT local variables, arguments or any 314structures, various perl stacks but NOT local variables, arguments or any
317C context data). This is a rough indication of how much memory it might 315C context data). This is a rough indication of how much memory it might
318use. 316use.
319 317
318=item ($real, $cpu) = $state->times
319
320Returns the real time and cpu times spent in the given C<$state>. See
321C<Coro::State::enable_times> for more info.
322
323=item $state->trace ($flags)
324
325Internal function to control tracing. I just mention this so you can stay
326away from abusing it.
327
328=back
329
330=head3 METHODS FOR C CONTEXTS
331
332Most coros only consist of some Perl data structures - transfering to a
333coro just reconfigures the interpreter to continue somewhere else.
334
335However. this is not always possible: For example, when Perl calls a C/XS function
336(such as an event loop), and C then invokes a Perl callback, reconfiguring
337the interpreter is not enough. Coro::State detects these cases automatically, and
338attaches a C-level thread to each such Coro::State object, for as long as necessary.
339
340The C-level thread structure is called "C context" (or cctxt for short),
341and can be quite big, which is why Coro::State only creates them as needed
342and can run many Coro::State's on a single cctxt.
343
344This is mostly transparent, so the following methods are rarely needed.
345
346=over 4
347
320=item $state->has_cctx 348=item $state->has_cctx
321 349
322Returns whether the state currently uses a cctx/C context. An active 350Returns whether the state currently uses a cctx/C context. An active
323state always has a cctx, as well as the main program. Other states only 351state always has a cctx, as well as the main program. Other states only
324use a cctxts when needed. 352use a cctxts when needed.
325 353
326=item Coro::State::force_cctx 354=item Coro::State::force_cctx
327 355
328Forces the allocation of a C context for the currently running coro 356Forces the allocation of a private cctxt for the currently executing
329(if not already done). Apart from benchmarking there is little point 357Coro::State even though it would not normally ned one. Apart from
330in doing so, however. 358benchmarking or testing Coro itself, there is little point in doing so,
359however.
331 360
332=item $ncctx = Coro::State::cctx_count 361=item $ncctx = Coro::State::cctx_count
333 362
334Returns the number of C-level thread contexts allocated. If this number is 363Returns the number of C contexts allocated. If this number is very high
335very high (more than a dozen) it might be beneficial to identify points of 364(more than a dozen) it might be beneficial to identify points of C-level
336C-level recursion (perl calls C/XS, which calls perl again which switches 365recursion (Perl calls C/XS, which calls Perl again which switches coros
337coros - this forces an allocation of a C-level thread context) in your 366- this forces an allocation of a C context) in your code and moving this
338code and moving this into a separate coro. 367into a separate coro.
339 368
340=item $nidle = Coro::State::cctx_idle 369=item $nidle = Coro::State::cctx_idle
341 370
342Returns the number of allocated but idle (currently unused and free for 371Returns the number of allocated but idle (currently unused and free for
343reuse) C level thread contexts. 372reuse) C contexts.
344 373
345=item $old = Coro::State::cctx_max_idle [$new_count] 374=item $old = Coro::State::cctx_max_idle [$new_count]
346 375
347Coro caches C contexts that are not in use currently, as creating them 376Coro caches C contexts that are not in use currently, as creating them
348from scratch has some overhead. 377from scratch has some overhead.
… …
352default being C<4>. 381default being C<4>.
353 382
354=item $old = Coro::State::cctx_stacksize [$new_stacksize] 383=item $old = Coro::State::cctx_stacksize [$new_stacksize]
355 384
356Returns the current C stack size and optionally sets the new I<minimum> 385Returns the current C stack size and optionally sets the new I<minimum>
357stack size to C<$new_stacksize> I<long>s. Existing stacks will not 386stack size to C<$new_stacksize> I<pointers>s. Existing stacks will not
358be changed, but Coro will try to replace smaller stacks as soon as 387be changed, but Coro will try to replace smaller stacks as soon as
359possible. Any Coro::State that starts to use a stack after this call is 388possible. Any Coro::State that starts to use a stack after this call is
360guaranteed this minimum stack size. 389guaranteed this minimum stack size.
361 390
362Please note that coros will only need to use a C-level stack if the 391Please note that coros will only need to use a C-level stack if the
363interpreter recurses or calls a function in a module that calls back into 392interpreter recurses or calls a function in a module that calls back into
364the interpreter, so use of this feature is usually never needed. 393the interpreter, so use of this feature is usually never needed.
365 394
395=back
396
397=head2 FUNCTIONS
398
399=over 4
400
366=item @states = Coro::State::list 401=item @states = Coro::State::list
367 402
368Returns a list of all states currently allocated. 403Returns a list of all Coro::State objects currently allocated. This
404includes all derived objects (such as L<Coro> threads).
369 405
370=item $was_enabled = Coro::State::enable_times [$enable] 406=item $was_enabled = Coro::State::enable_times [$enable]
371 407
372Enables/disables/queries the current state of per-thread real and 408Enables/disables/queries the current state of per-thread real and
373cpu-time gathering. 409cpu-time gathering.
… …
381 417
382Enabling time profiling slows down thread switching by a factor of 2 to 418Enabling time profiling slows down thread switching by a factor of 2 to
38310, depending on platform on hardware. 41910, depending on platform on hardware.
384 420
385The times will be displayed when running C<Coro::Debug::command "ps">, and 421The times will be displayed when running C<Coro::Debug::command "ps">, and
386cna be queried by calling C<< $state->times >>. 422can be queried by calling C<< $state->times >>.
387 423
388=item ($real, $cpu) = $state->times 424=back
389 425
390Returns the real time and cpu times spent in the given C<$state>. See 426=head3 CLONING
391C<Coro::State::enable_times> for more info. 427
428=over 4
392 429
393=item $clone = $state->clone 430=item $clone = $state->clone
394 431
395This exciting method takes a Coro::State object and clones it, i.e., it 432This exciting method takes a Coro::State object and clones it, i.e., it
396creates a copy. This makes it possible to restore a state more than once, 433creates a copy. This makes it possible to restore a state more than once,

Diff Legend

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