From 688a1314e60b0e58d5325f50c02552e3018c5025 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 23 Dec 2023 15:08:26 -0600 Subject: [PATCH] [DOC] Clean up doc for File#flock (#9332) --- file.c | 94 +++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 61 insertions(+), 33 deletions(-) diff --git a/file.c b/file.c index fd1fbf2d97..fee3840452 100644 --- a/file.c +++ b/file.c @@ -5222,47 +5222,75 @@ rb_thread_flock(void *data) return (VALUE)ret; } -/* +/* :markup: markdown + * * call-seq: - * file.flock(locking_constant) -> 0 or false + * flock(locking_constant) -> 0 or false * - * Locks or unlocks a file according to locking_constant (a - * logical or of the values in the table below). - * Returns false if File::LOCK_NB is specified and the - * operation would otherwise have blocked. Not available on all - * platforms. + * Locks or unlocks a file according to the given `locking_constant`, + * a bitwise OR of the values in the table below. * - * Locking constants (in class File): + * Not available on all platforms. * - * 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. + * Returns `false` if `File::LOCK_NB` is specified and the operation would have blocked; + * otherwise returns `0`. + *
* + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Locking Constants
ConstantLockEffect
File::LOCK_EXExclusiveOnly one process may hold an exclusive lock for self at a time.
File::LOCK_NBNon-blocking + * No blocking; may be combined with other `File::LOCK_SH` or `File::LOCK_EX` + * using the bitwise OR operator |. + *
File::LOCK_SHSharedMultiple processes may each hold a shared lock for self at the same time.
File::LOCK_UNUnlockRemove an existing lock held by this process.
+ * + *
* 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) - * } + * ```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 read lock - * File.open("counter", "r") {|f| - * f.flock(File::LOCK_SH) - * p f.read - * } + * # Read the counter using a shared lock. + * File.open('counter', 'r') do |f| + * f.flock(File::LOCK_SH) + * f.read + * end + * ``` * */