package POSIX::Yield;

use version;our $VERSION=qv('0.0.1');
use strict;
use warnings;
use Inline C => <<'END_OF_CODE';
#include <sched.h>

int _yield() {
    return sched_yield() == 0 ? 1 : 0 ;
}
END_OF_CODE

use base qw(Exporter);
our @EXPORT_OK = qw(yield);

sub yield {
    _yield() or return;
}
1;
__END__

=head1 NAME

POSIX::Yield - yield the processor

=head1 VERSION

This documentation refers to POSIX::Yield 0.0.1.

=head1 SYNOPSIS

use POSIX::Yield qw(yield);

yield();

=head1 DESCRIPTION

This module provides one function, C<yield()>, which calls the POSIX.1b C<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 C<nice()> function from the C<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 C<sched_yield(2)> man page and your operating systems scheduling documentation for more details.

=head1 INTERFACE

=head2 Subroutines

=over

=item C<yield()>

Executes the C<sched_yield> 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::Yield> to implement a spinlock:

    use Fcntl qw(:flock);
    use POSIX::Yield qw(yield);

    my $lock;

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

    while (!flock($lock, LOCK_EX|LOCK_NB)) {
        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 the process which is handling the lock at the moment and allowing it to be released. You should B<not> use C<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::Yield depends on the following modules:

=over

=item *

Inline::C

=item *

version

=back
    
and a POSIX environment

=head1 SEE ALSO

<sched_yield(2) man page

=head1 BUGS AND LIMITATIONS

None known