DB_File::Lock(3pm)

1Lock(3)               User Contributed Perl Documentation              Lock(3)
2
3
4

NAME

6       DB_File::Lock - Locking with flock wrapper for DB_File
7

SYNOPSIS

9        use DB_File::Lock;
10        use Fcntl qw(:flock O_RDWR O_CREAT);
11
12        $locking = "read";
13        $locking = "write";
14        $locking = {
15            mode            => "read",
16            nonblocking     => 0,
17            lockfile_name   => "/path/to/shared.lock",
18            lockfile_mode   => 0600,
19        };
20
21        [$X =] tie %hash,  'DB_File::Lock', $filename, $flags, $mode, $DB_HASH, $locking;
22        [$X =] tie %hash,  'DB_File::Lock', $filename, $flags, $mode, $DB_BTREE, $locking;
23        [$X =] tie @array, 'DB_File::Lock', $filename, $flags, $mode, $DB_RECNO, $locking;
24
25        # or place the DB_File arguments inside a list reference:
26        [$X =] tie %hash,  'DB_File::Lock', [$filename, $flags, $mode, $DB_HASH], $locking;
27
28        ...use the same way as DB_File for the rest of the interface...
29

DESCRIPTION

31       This module provides a wrapper for the DB_File module, adding locking.
32
33       When you need locking, simply use this module in place of DB_File and
34       add an extra argument onto the tie command specifying if the file
35       should be locked for reading or writing.
36
37       The alternative is to write code like:
38
39         open(LOCK, "<$db_filename.lock") or die;
40         flock(LOCK, LOCK_SH) or die;
41         tie(%db_hash, 'DB_File', $db_filename,  O_RDONLY, 0600, $DB_HASH) or die;
42         ... then read the database ...
43         untie(%db_hash);
44         close(LOCK);
45
46       This module lets you write
47
48         tie(%db_hash, 'DB_File::Lock', $db_filename,  O_RDONLY, 0600, $DB_HASH, 'read') or die;
49         ... then read the database ...
50         untie(%db_hash);
51
52       This is better for two reasons:
53
54       (1) Less cumbersome to write.
55
56       (2) A fatal exception in the code working on the database which does
57       not lead to process termination will probably not close the lockfile
58       and therefore cause a dropped lock.
59

USAGE DETAILS

61       Tie to the database file by adding an additional locking argument to
62       the list of arguments to be passed through to DB_File, such as:
63
64         tie(%db_hash, 'DB_File::Lock', $db_filename,  O_RDONLY, 0600, $DB_HASH, 'read');
65
66       or enclose the arguments for DB_File in a list reference:
67
68         tie(%db_hash, 'DB_File::Lock', [$db_filename,  O_RDONLY, 0600, $DB_HASH], 'read');
69
70       The filename used for the lockfile defaults to "$filename.lock" (the
71       filename of the DB_File with ".lock" appended). Using a lockfile
72       separate from the database file is recommended because it prevents
73       weird interactions with the underlying database file library
74
75       The additional locking argument added to the tie call can be:
76
77       (1) "read" -- acquires a shared lock for reading
78
79       (2) "write" -- acquires an exclusive lock for writing
80
81       (3) A hash with the following keys (all optional except for the
82       "mode"):
83
84       mode
85           the locking mode, "read" or "write".
86
87       lockfile_name
88           specifies the name of the lockfile to use. Default is
89           "$filename.lock".  This is useful for locking multiple resources
90           with the same lockfiles.
91
92       nonblocking
93           determines if the flock call on the lockfile should block waiting
94           for a lock, or if it should return failure if a lock can not be
95           immediately attained. If "nonblocking" is set and a lock can not be
96           attained, the tie command will fail.  Currently, I'm not sure how
97           to differentiate this between a failure form the DB_File layer.
98
99       lockfile_mode
100           determines the mode for the sysopen call in opening the lockfile.
101           The default mode will be formulated to allow anyone that can read
102           or write the DB_File permission to read and write the lockfile.
103           (This is because some systems may require that one have write
104           access to a file to lock it for reading, I understand.) The umask
105           will be prevented from applying to this mode.
106
107       Note: One may import the same values from DB_File::Lock as one may
108       import from DB_File.
109

GOOD LOCKING ETIQUETTE

111       To avoid locking problems, realize that it is critical that you release
112       the lock as soon as possible. See the lock as a "hot potato", something
113       that you must work with and get rid of as quickly as possible. See the
114       sections of code where you have a lock as "critical" sections. Make
115       sure that you call "untie" as soon as possible.
116
117       It is often better to write:
118
119         # open database file with lock
120         # work with database
121         # lots of processing not related to database
122         # work with database
123         # close database and release lock
124
125       as:
126
127         # open database file with lock
128         # work with database
129         # close database and release lock
130
131         # lots of processing not related to database
132
133         # open database file with lock
134         # work with database
135         # close database and release lock
136
137       Also realize that when acquiring two locks at the same time, a deadlock
138       situation can be caused.
139
140       You can enter a deadlock situation if two processes simultaneously try
141       to acquire locks on two separate databases. Each has locked only one of
142       the databases, and cannot continue without locking the second. Yet this
143       will never be freed because it is locked by the other process. If your
144       processes all ask for their DB files in the same order, this situation
145       cannot occur.
146

OTHER LOCKING MODULES

148       There are three locking wrappers for DB_File in CPAN right now. Each
149       one implements locking differently and has different goals in mind. It
150       is therefore worth knowing the difference, so that you can pick the
151       right one for your application.
152
153       Here are the three locking wrappers:
154
155       Tie::DB_Lock -- DB_File wrapper which creates copies of the database
156       file for read access, so that you have kind of a multiversioning
157       concurrent read system. However, updates are still serial. Use for
158       databases where reads may be lengthy and consistency problems may
159       occur.
160
161       Tie::DB_LockFile -- DB_File wrapper that has the ability to lock and
162       unlock the database while it is being used. Avoids the tie-before-flock
163       problem by simply re-tie-ing the database when you get or drop a lock.
164       Because of the flexibility in dropping and re-acquiring the lock in the
165       middle of a session, this can be massaged into a system that will work
166       with long updates and/or reads if the application follows the hints in
167       the POD documentation.
168
169       DB_File::Lock (this module) -- extremely lightweight DB_File wrapper
170       that simply flocks a lockfile before tie-ing the database and drops the
171       lock after the untie.  Allows one to use the same lockfile for multiple
172       databases to avoid deadlock problems, if desired. Use for databases
173       where updates are reads are quick and simple flock locking semantics
174       are enough.
175
176       (This text duplicated in the POD documentation, by the way.)
177

AUTHOR

179       David Harris <dharris@drh.net>
180
181       Helpful insight from Stas Bekman <stas@stason.org>
182