This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Implement use attrs qw(locked package);
[perl5.git] / ext / attrs / attrs.pm
1 package attrs;
2 require DynaLoader;
3 use vars '@ISA';
4 @ISA = 'DynaLoader';
5
6 use vars qw($VERSION);
7 $VERSION = "1.0";
8
9 =head1 NAME
10
11 attrs - set/get attributes of a subroutine
12
13 =head1 SYNOPSIS
14
15     sub foo {
16         use attrs qw(locked method);
17         ...
18     }
19
20     @a = attrs::get(\&foo);
21
22 =head1 DESCRIPTION
23
24 This module lets you set and get attributes for subroutines.
25 Setting attributes takes place at compile time; trying to set
26 invalid attribute names causes a compile-time error. Calling
27 C<attr::get> on a subroutine reference or name returns its list
28 of attribute names. Notice that C<attr::get> is not exported.
29 Valid attributes are as follows.
30
31 =over
32
33 =item method
34
35 Indicates that the invoking subroutine is a method.
36
37 =item package
38
39 If the subroutine is locked, lock the package in which it is
40 defined.
41
42 =item locked
43
44 Setting this attribute is only meaningful when the subroutine or
45 method is to be called by multiple threads. When the B<package>
46 attribute is set then before executing the subroutine or method
47 perl acquires a lock on the package in which the subroutine is
48 defined. 
49
50 Otherwise, when set on a method subroutine (i.e. one
51 marked with the B<method> attribute above), perl ensures that any
52 invocation of it implicitly locks its first argument before
53 execution. When set on a non-method subroutine,
54 (without a B<package> attribute) perl ensures that a lock is taken 
55 on the subroutine itself before execution. The semantics of the
56 lock are exactly those of one explicitly taken with the C<lock> 
57 operator immediately after the subroutine is entered.
58
59 =back
60
61 =cut
62
63 bootstrap attrs $VERSION;
64
65 1;