Skip to content

bpo-36794: Document that Lock.acquire is fair. #13082

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 1 commit into from
May 29, 2019
Merged

bpo-36794: Document that Lock.acquire is fair. #13082

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 7 additions & 0 deletions Doc/library/asyncio-sync.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,13 @@ Lock
This method waits until the lock is *unlocked*, sets it to
*locked* and returns ``True``.

When more than one coroutine is blocked in :meth:`acquire`
waiting for the lock to be unlocked, only one coroutine
eventually proceeds.

Acquiring a lock is *fair*: the coroutine that proceeds will be
Copy link
Member

Choose a reason for hiding this comment

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

I don't quite understand what you mean by "fair"? It reads oddly to me.

Copy link
Contributor Author

@hniksic hniksic May 29, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

"Fair" is a standard term for the kind of lock that avoids starvation by treating waiters as first-come first-serve; see e.g. here.

It should be fine if someone is not familiar with the term because the rest of the sentence explains it.

Copy link
Contributor

Choose a reason for hiding this comment

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

I see fair in multithreading context first time here.
Not sure if this is standard term.
Can we avoid this word in documentation?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The term fair is widely used in this meaning across programming languages, e.g. kotlin, java, golang, c++, Python.

The idea is to use the technical term to help people already familiar with the concept, and also explain it in the rest of the sentence. That kind of usage doesn't hinder understanding, and it can even help the reader when encountering the term later.

Copy link
Contributor

Choose a reason for hiding this comment

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

In mentioned links fairness is used in java. kotlin inherits this term.
Golang has fairness in documentation only.
C++ and Python links point on stackoverflow which is nice site but not the official python documentation.

Docs for python threading doesn't mention fairness. I think if we add the term we should enumerate it in python glossary as well.

I still not convinced that this is required

Copy link
Contributor

Choose a reason for hiding this comment

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

@1st1 what is your opinion?

Copy link
Member

Choose a reason for hiding this comment

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

I think using "fair" is fine here, but not really necessary as the text after the colon explains it in detail anyways.

Copy link
Contributor

Choose a reason for hiding this comment

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

Ok, if Yuri agree

the first coroutine that started waiting on the lock.

.. method:: release()

Release the lock.
Expand Down