package POSIX::SchedYield;

use version; our $VERSION = qv('0.0.2');

use 5.006;
use warnings;
use strict;

require Exporter;

our @ISA = qw(Exporter);

our @EXPORT_OK = qw(sched_yield);

require XSLoader;
XSLoader::load('POSIX::SchedYield', $VERSION);

1;

__END__

=head1 NAME

POSIX::SchedYield - execute POSIX.1b system call sched_yield(2)

=head1 VERSION

This documentation refers to POSIX::SchedYield 0.0.2.

=head1 SYNOPSIS

use POSIX::SchedYield qw(sched_yield);

sched_yield();

=head1 DESCRIPTION

This module provides one function, C<sched_yield()>, which executes the POSIX.1b sched_yield system call. It relinquishes the processor without blocking, allowing other processes to run. This does B<not> change the process priority (see the L<nice|POSIX/nice> function from the L<POSIX|POSIX> module for that), so if your process is currently the one with the highest priority it will continue to run without interruption. See the sched_yield(2) man page and your operating systems scheduling documentation for more details.

On most systems, the L<threads> module method L<yield()|threads/yield> will also use the sched_yield system call, so you can use that instead, if you prefer. POSIX::SchedYield is more explicit, will work with older and unthreaded versions of Perl, and will always call sched_yield, whereas the C<threads> implementation may change at some point.

=head1 INTERFACE

=head2 Subroutines

=over

=item C<sched_yield()>

Executes the sched_yield(2) system call. No parameters can be passed, the function returns 1 on sucess, undef on failure.

=back

=head1 EXAMPLES / USAGE

You can use C<POSIX::SchedYield> to implement a spinlock:

    use Fcntl qw(:flock);
    use POSIX::SchedYield qw(sched_yield);

    my $lock;

    PrivoxyWindowOpen($lock,">","/tmp/file") or die "Can't open";

    while (!flock($lock, LOCK_EX|LOCK_NB)) {
        sched_yield();
    }
    #.. do something ..
    flock($lock, LOCK_UN) or die "Can't release lock";
    close $lock or die "Can't close lockfile";

This will yield the processor when a process is unable to obtain a lock, thus hopefully giving control back to another process which is handling the lock at the moment and allowing it to be released. You should B<not> use sched_yield this way if you're expecting the lock to be held for any extended period of time (for example if the locking process waits for I/O with the lock held), because this will cause your yielding process to hog the CPU as it retries,yields,retries,yields etc.

=head1 DEPENDENCIES

POSIX::SchedYield depends on the L<version|version> module and a POSIX environment

=head1 SEE ALSO

sched_yield(2) man page, L<threads|threads> module

=head1 BUGS

Please report any bugs or feature requests to
C<bug-posix-schedyield@rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POSIX-SchedYield>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 ACKNOWLEDGEMENTS

Thanks to http://www.perlmonks.org, especially dave_the_m, Joost and BrowserUK for excellent advice.

=head1 COPYRIGHT & LICENSE

Copyright 2005 Marc Beyer, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/copyleft/gpl.html

=cut