comment on

Fellow monks,

while playing around with benchmarks for this node, I came across the sched_yield system call. This seems to be useful enough to expose it to Perl programs, so I wrote up a trivial module using Inline::C. Now I have a number of questions and I'd be happy if you could take the time to answer some of them:

Is this CPAN-worthy or entirely too trivial?
If I do submit it to CPAN should I change it to XS or is Inline::C fine?
Namespace - should this live under the POSIX namespace or somewhere else? Proc::POSIX:: or POSIX::Proc:: perhaps?
Name - since the system call is sched_yield and known under that name, maybe it'd be better to call the Module *::SchedYield? That's uglier but may be more intuitive to people who know their POSIX
Export - I vastly prefer modules to not pollute the namespace by default and only do EXPORT_OK. But in this particular case it seems a bit silly (as all the module does is export one subroutine and you wouldn't load it unless you wanted that sub). Should I export by default?
Success checks - returning 0 on success is unperlish. OTOH, this module can only be useful if calls to yield() are as cheap as possible, so I figured I'd choose the cheapest type of success/error checking available. Is it enough?
At the moment I can only test sched_yield on Linux. I've googled around and it should do the right thing on other POSIX-compliant systems as well (albeit there is some disagreement on behaviour and implementation). Are any monks aware of gotchas I should point out for other systems?
Is it sensible to have an entire module for just this one function or should I rather try to submit patches to other modules which may make use of this (Parallel::ForkManager would be an example where I could see it as being useful).

Any other comments and guidances are also more than welcome. Here's the code:

Update: now with Readmore tags, as suggested

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.1
+b C<sched_yield()> system call. It relinquishes the processor without
+ blocking, allowing other processes to run. This does B<not> change t
+he process priority (see the C<nice()> function from the C<POSIX> mod
+ule for that), so if your process is currently the one with the highe
+st priority it will continue to run without interruption. See the C<s
+ched_yield(2)> man page and your operating systems scheduling documen
+tation 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 loc
+k, thus hopefully giving control back to the process which is handlin
+g 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 f
+or any extended period of time (for example if the locking process wa
+its for I/O with the lock held), because this will cause your yieldin
+g 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
[download]

Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. -- Brian W. Kernighan

In reply to RFC: Proposed module POSIX::Yield by tirwhan

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		`&`
	<		`<`
	>		`>`
	[		`[`
	]		`]`

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.