diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2023-12-23 15:08:26 -0600 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-12-23 16:08:26 -0500 |
commit | 688a1314e60b0e58d5325f50c02552e3018c5025 (patch) | |
tree | 5a7fa0d213cee12978b7fdddafae946e203f8b83 /file.c | |
parent | 47f33c38481d79563271f042946d0f3165d8b638 (diff) |
[DOC] Clean up doc for File#flock (#9332)
Diffstat (limited to 'file.c')
-rw-r--r-- | file.c | 102 |
1 files changed, 65 insertions, 37 deletions
@@ -5222,47 +5222,75 @@ rb_thread_flock(void *data) return (VALUE)ret; } -/* +/* :markup: markdown + * * call-seq: - * file.flock(locking_constant) -> 0 or false - * - * Locks or unlocks a file according to <i>locking_constant</i> (a - * logical <em>or</em> of the values in the table below). - * Returns <code>false</code> if File::LOCK_NB is specified and the - * operation would otherwise have blocked. Not available on all - * platforms. - * - * Locking constants (in class File): - * - * LOCK_EX | Exclusive lock. Only one process may hold an - * | exclusive lock for a given file at a time. - * ----------+------------------------------------------------ - * LOCK_NB | Don't block when locking. May be combined - * | with other lock options using logical or. - * ----------+------------------------------------------------ - * LOCK_SH | Shared lock. Multiple processes may each hold a - * | shared lock for a given file at the same time. - * ----------+------------------------------------------------ - * LOCK_UN | Unlock. + * flock(locking_constant) -> 0 or false + * + * Locks or unlocks a file according to the given `locking_constant`, + * a bitwise OR of the values in the table below. + * + * Not available on all platforms. * + * Returns `false` if `File::LOCK_NB` is specified and the operation would have blocked; + * otherwise returns `0`. + * <br> + * + * <table> + * <tr> + * <th colspan="3">Locking Constants</th> + * </tr> + * <tr> + * <th>Constant</th> + * <th>Lock</th> + * <th>Effect</th> + * </tr> + * <tr> + * <td><tt>File::LOCK_EX</tt></td> + * <td>Exclusive</td> + * <td>Only one process may hold an exclusive lock for <tt>self</tt> at a time.</td> + * </tr> + * <tr> + * <td><tt>File::LOCK_NB</tt></td> + * <td>Non-blocking</td> + * <td> + * No blocking; may be combined with other `File::LOCK_SH` or `File::LOCK_EX` + * using the bitwise OR operator <tt>|</tt>. + * </td> + * </tr> + * <tr> + * <td><tt>File::LOCK_SH</tt></td> + * <td>Shared</td> + * <td>Multiple processes may each hold a shared lock for <tt>self</tt> at the same time.</td> + * </tr> + * <tr> + * <td><tt>File::LOCK_UN</tt></td> + * <td>Unlock</td> + * <td>Remove an existing lock held by this process.</td> + * </tr> + * </table> + * + * <br> * Example: * - * # update a counter using write lock - * # don't use "w" because it truncates the file before lock. - * File.open("counter", File::RDWR|File::CREAT, 0644) {|f| - * f.flock(File::LOCK_EX) - * value = f.read.to_i + 1 - * f.rewind - * f.write("#{value}\n") - * f.flush - * f.truncate(f.pos) - * } - * - * # read the counter using read lock - * File.open("counter", "r") {|f| - * f.flock(File::LOCK_SH) - * p f.read - * } + * ```ruby + * # Update a counter using an exclusive lock. + * # Don't use File::WRONLY because it truncates the file. + * File.open('counter', File::RDWR | File::CREAT, 0644) do |f| + * f.flock(File::LOCK_EX) + * value = f.read.to_i + 1 + * f.rewind + * f.write("#{value}\n") + * f.flush + * f.truncate(f.pos) + * end + * + * # Read the counter using a shared lock. + * File.open('counter', 'r') do |f| + * f.flock(File::LOCK_SH) + * f.read + * end + * ``` * */ |