8000 [DOC] Clean up doc for File#flock by BurdetteLamar · Pull Request #9332 · ruby/ruby · GitHub
[go: up one dir, main page]
Skip to content

[DOC] Clean up doc for File#flock #9332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Dec 23, 2023
Merged

[DOC] Clean up doc for File#flock #9332

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8ef7ecb
RDoc for Complex
BurdetteLamar Dec 20, 2023
3e6d22c
RDoc for Complex
BurdetteLamar Dec 22, 2023
90c1f19
RDoc for Complex
BurdetteLamar Dec 22, 2023
97b277d
RDoc for Complex
BurdetteLamar Dec 22, 2023
35788b6
Update complex.c
BurdetteLamar Dec 23, 2023
1659b2d
Clean up doc for File#flock
BurdetteLamar Dec 23, 2023
17b9070
RDoc for Complex
BurdetteLamar Dec 23, 2023
a7adb00
Merge branch 'complex_doc' of https://github.com/BurdetteLamar/ruby i…
BurdetteLamar Dec 23, 2023
3b3b397
Update file.c
BurdetteLamar Dec 23, 2023
c521512
Merge branch 'file_doc' of https://github.com/BurdetteLamar/ruby into…
BurdetteLamar Dec 23, 2023
17c93ad
Update file.c
BurdetteLamar Dec 23, 2023
6f2442a
Update file.c
BurdetteLamar Dec 23, 2023
4f57384
Merge branch 'master' into file_doc
peterzhu2118 Dec 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 65 additions & 37 deletions file.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Comment on lines +5239 to +5271
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems duplicate of File::Constants@Locking but different a little.
Why not just linking?

Or a markdown table.

 *  [Locking Constants](rdoc-ref:File::Constants@Locking)
 *
 *  | Constant      | Lock         | Effect
 *  |---------------|--------------|-------------------------------------------------------------------
 *  | File::LOCK_EX | Exclusive    | Only one process may hold an exclusive lock for +self+ at a time.
 *  | File::LOCK_NB | Non-blocking | No blocking; may be combined with other +File::LOCK_SH+ or +File::LOCK_EX+ using the bitwise OR operator <tt>\|</tt>
 *  | File::LOCK_SH | Shared       | Multiple processes may each hold a shared lock for +self+ at the same time.
 *  | File::LOCK_UN | Unlock       | Remove an existing lock held by this process.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems duplicate of File::Constants@Locking but different a little. Why not just linking?

Or a markdown table.

 *  [Locking Constants](rdoc-ref:File::Constants@Locking)
 *
 *  | Constant      | Lock         | Effect
 *  |---------------|--------------|-------------------------------------------------------------------
 *  | File::LOCK_EX | Exclusive    | Only one process may hold an exclusive lock for +self+ at a time.
 *  | File::LOCK_NB | Non-blocking | No blocking; may be combined with other +File::LOCK_SH+ or +File::LOCK_EX+ using the bitwise OR operator <tt>\|</tt>
 *  | File::LOCK_SH | Shared       | Multiple processes may each hold a shared lock for +self+ at the same time.
 *  | File::LOCK_UN | Unlock       | Remove an existing lock held by this process.

@nobu, my aim here is reformatting from RDoc to markdown, not (for the most part) revision; the existing crude "table" has been here at least since before version 2.7.0, so I've retained (but reformatted) it.

I tried the markdown table (Github flavored?), but it did not work for me; do I need to enable something?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used the markdown table and it correctly generated a table for me. I'm on RDoc 6.6.2.

Screenshot 2023-12-24 at 10 24 48 AM

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am running 6,3,1, gem install rdoc failed (problems building native extensions). How to proceed?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What Ruby are you running and what is the error?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ruby 3.0.2p107 (2021-07-07 revision 0db68f0) [x86_64-linux-gnu] on my LInux machine.

Over on my Windows machine, I'm running ruby 3,2,2 and rdoc 6.5.0, where the markdown table works fine. Will migrate there and revise.

*
* <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
* ```
*
*/

Expand Down
0