fullock(3)

💖 fullock — the manual page, but make it make sense 💖

okay bestie, sit down, hydrate, because we're about to talk about fullock(3) and it's actually iconic.

---

✨ NAME ✨

fullock — the Fast User Level LOCK (FULLOCK) library for C/C++, brought to you so your threads and your processes can share nice things without, like, destroying each other.

---

🌸 SYNOPSIS 🌸

bestie. the synopsis is literally just:

Please see fullock.h for full description.

that's it. that's the whole synopsis. go read the header, iykyk 💅

---

🦋 DESCRIPTION 🦋

okay so fullock is open-source software — a user level lock library — and it's supported by Yahoo! JAPAN, which is main character energy honestly. it runs at the user level and it gives you two types of lock:

• One is a shared reader/writer lock, and it has the exact same functionality as pthread_rwlock.
• The other is a shared mutex lock, and it also has the exact same functionality as pthread_mutex.

Here's the primary fullock features, no cap:

1. fullock is a thread safety library which can be used for multi-processing as well as for multi-threading.
2. fullock releases a mutex lock safely even if a lock owner process exit with 0 in which case OS doesn't release the lock.
3. fullock provides a shared reader/writer lock. A lock owner thread can get another lock again without deadlock.

and if you want more details (you do, you're nosy, it's cute), please visit our website at:

https://github.com/yahoojapan/fullock

---

👑 FUNCTIONS 👑

FULLOCK provides the following programming interface — here's the whole roster, all of them, every single one, because we don't gatekeep:

void fullock_print_version(...)
bool fullock_set_no_robust(...)
bool fullock_set_low_robust(...)
bool fullock_set_high_robust(...)
bool fullock_set_noretry_allow_nomap(...)
bool fullock_set_noretry_deny_nomap(...)
bool fullock_set_retry_allow_nomap(...)
bool fullock_set_retry_deny_nomap(...)
bool fullock_set_no_freeunit(...)
bool fullock_set_fd_freeunit(...)
bool fullock_set_offset_freeunit(...)
bool fullock_set_robust_check_count(...)
bool fullock_reinitialize(...)
bool fullock_reinitialize_ex(...)
int fullock_mutex_lock(...)
int fullock_mutex_trylock(...)
int fullock_mutex_timedlock(...)
int fullock_mutex_unlock(...)
int fullock_rwlock_rdlock(...)
int fullock_rwlock_tryrdlock(...)
int fullock_rwlock_timedrdlock(...)
int fullock_rwlock_wrlock(...)
int fullock_rwlock_trywrlock(...)
int fullock_rwlock_timedwrlock(...)
int fullock_rwlock_unrwlock(...)
bool fullock_rwlock_islocked(...)
int fullock_cond_timedwait(...)
int fullock_cond_wait(...)
int fullock_cond_signal(...)
int fullock_cond_broadcast(...)

look at that list. so many little helpers. they're all so valid 🥹

---

🧚 ENVIRONMENT 🧚

so fullock uses some very useful environments for debug that change its behaviour. yes, they change how it behaves, that's literally the point.

• FLCKDBGMODE — specifies debugging level: INFO/WAN/ERR/SILENT
• FLCKDBGFILE — output file path for message (default: stderr)
• FLCKAUTOINIT — specify YES/NO, if this environment has YES, fullock does not initialize shared memory file. This environment is for debugging.
• FLCKROBUSTMODE — specify NO/LOW/HIGH for robust mode.
• FLCKNOMAPMODE — specify ALLOW(ALLOW_NORETRY) / DENY(DENY_NORETRY) / ALLOW_RETRY / DENY_RETRY for fault tolerant. This value determines the behavior of the case can not be mapped.
• FLCKFREEUNITMODE — specify NO/FD/OFFSET/ALWAYS, it specifies the open method of unit management area to be used in the reader/writer lock.
• FLCKROBUSTCHKCNT — If fullock is operating in a high robust mode, this value sets the processing frequency for the deadlock detection.
• FLCKUMASK — specify umask for the shared memory file which is made by fullock.
• FLCKDIRPATH — specify directory path for the shared memory file which is made by fullock.
• FLCKFILENAME — specify the shared memory file name which is made by fullock.
• FLCKFILECNT — specify file count for the reader/writer lock.
• FLCKOFFETCNT — specify offset count for the reader/writer lock.
• FLCKLOCKERCNT — specify the process(thread) count for the reader/writer lock and mutex at same time.
• FLCKNMTXCNT — specify count for named mutex.
• FLCKNCONDCNT — specify count for named condition variable.
• FLCKWAITERCNT — specify named condition waiter count for named condition variable.

that's a lot of env vars and every single one of them matters. read them. love them. set them carefully. 🫶

---

🌈 SEE ALSO 🌈

The web site can be found at:

https://github.com/yahoojapan/fullock

---

💀 REPORTING BUGS 💀

okay first of all: Please make sure you use the latest version in the web site:

https://github.com/yahoojapan/fullock

Then, please submit your questions or comments here:

https://github.com/yahoojapan/fullock/issues

not me asking you to update first before you yell at us, but like, genuinely, please update first 🙈

---

🎀 AUTHORS 🎀

Takeshi Nakatani <ggtakec@gmail.com>

shoutout to the author, absolute legend, we stan 🫡

---

⭐ COPYRIGHT ⭐

MIT License

Copyright (C) 2015 Yahoo Japan Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

bestie that's the whole MIT license, all caps included, don't skip it, it's legally load-bearing 💅

---

and that's the page!! this one's from the FULLOCK manual, dated May 2015, and it lives at fullock(3) in section 3. go forth, lock things responsibly, and remember: no deadlock, only slay. 💖✨