view release on metacpan or  search on metacpan

Coro/State.pm  view on Meta::CPAN

It is, however, quite safe to swap some normal variable with
another. For example, L<PApp::SQL> stores the default database handle in
C<$PApp::SQL::DBH>. To make this a per-thread variable, use this:

   my $private_dbh = ...;
   $coro->swap_sv (\$PApp::SQL::DBH, \$private_dbh);

This results in C<$PApp::SQL::DBH> having the value of C<$private_dbh>
while it executes, and whatever other value it had when it doesn't
execute.

You can also swap hashes and other values:

   my %private_hash;
   $coro->swap_sv (\%some_hash, \%private_hash);

To undo an earlier C<swap_sv> call you must call C<swap_sv> with exactly
the same two variables in the same order (the references can be different,
it's the variables that they point to that count). For example, the
following sequence will remove the swap of C<$x> and C<$y>, while keeping
the swap of C<$x> and C<$z>:

   $coro->swap_sv (\$x, \$y);
   $coro->swap_sv (\$x, \$z);
   $coro->swap_sv (\$x, \$y);

=item $bytes = $state->rss

Returns the memory allocated by the coro (which includes static
structures, various perl stacks but NOT local variables, arguments or any
C context data). This is a rough indication of how much memory it might
use.

=item ($real, $cpu) = $state->times

Returns the real time and cpu times spent in the given C<$state>. See
C<Coro::State::enable_times> for more info.

=item $state->trace ($flags)

Internal function to control tracing. I just mention this so you can stay
away from abusing it.

=back

=head3 METHODS FOR C CONTEXTS

Most coros only consist of some Perl data structures - transferring to a
coro just reconfigures the interpreter to continue somewhere else.

However. this is not always possible: For example, when Perl calls a C/XS function
(such as an event loop), and C then invokes a Perl callback, reconfiguring
the interpreter is not enough. Coro::State detects these cases automatically, and
attaches a C-level thread to each such Coro::State object, for as long as necessary.

The C-level thread structure is called "C context" (or cctxt for short),
and can be quite big, which is why Coro::State only creates them as needed
and can run many Coro::State's on a single cctxt.

This is mostly transparent, so the following methods are rarely needed.

=over 4

=item $state->has_cctx

Returns whether the state currently uses a cctx/C context. An active
state always has a cctx, as well as the main program. Other states only
use a cctxts when needed.

=item Coro::State::force_cctx

Forces the allocation of a private cctxt for the currently executing
Coro::State even though it would not normally ned one. Apart from
benchmarking or testing Coro itself, there is little point in doing so,
however.

=item $ncctx = Coro::State::cctx_count

Returns the number of C contexts allocated. If this number is very high
(more than a dozen) it might be beneficial to identify points of C-level
recursion (Perl calls C/XS, which calls Perl again which switches coros
- this forces an allocation of a C context) in your code and moving this
into a separate coro.

=item $nidle = Coro::State::cctx_idle

Returns the number of allocated but idle (currently unused and free for
reuse) C contexts.

=item $old = Coro::State::cctx_max_idle [$new_count]

Coro caches C contexts that are not in use currently, as creating them
from scratch has some overhead.

This function returns the current maximum number of idle C contexts and
optionally sets the new amount. The count must be at least C<1>, with the
default being C<4>.

=item $old = Coro::State::cctx_stacksize [$new_stacksize]

Returns the current C stack size and optionally sets the new I<minimum>
stack size to C<$new_stacksize> (in units of pointer sizes, i.e. typically
4 on 32 bit and 8 on 64 bit hosts). Existing stacks will not be changed,
but Coro will try to replace smaller stacks as soon as possible. Any
Coro::State that starts to use a stack after this call is guaranteed this
minimum stack size.

Please note that coros will only need to use a C-level stack if the
interpreter recurses or calls a function in a module that calls back into
the interpreter, so use of this feature is usually never needed.

=back

=head2 FUNCTIONS

=over 4

=item @states = Coro::State::list

Returns a list of all Coro::State objects currently allocated. This