NaviServer - programmable web server
4.99  5.0

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

ns_rwlock(n) 5.0.0a naviserver "NaviServer Built-in Commands"

Name

ns_rwlock - Create, destroy, and manipulate read/write locks

Table Of Contents

Synopsis

Description

Create, destroy, and manipulate read/write locks.

COMMANDS

ns_rwlock create

Initializes a read/write lock and returns an ID for it.

ns_rwlock destroy rwlockid

Releases the resources associated with the specified read/write lock. The rwlockid argument is the read/write lock ID returned by ns_rwlock create when the lock was created.

In the current implementation, this operation is effectively a no-op, meaning the semaphore remains until the server shuts down.

ns_rwlock readeval rwlockid script

A convenience function to lock the specified rwlockid for reading, runs the script, and releases the lock. The command returns the result and any error condition of the executed script. If rwlockid does not exist, it will be auto-created, although this is generally not recommended.

ns_rwlock readlock rwlockid

Acquires a read lock. Multiple read locks can run concurrently without blocking each other. If a write lock is active, the acquisition of a read lock will block until the write lock is released.

ns_rwlock readunlock rwlockid

Releases a read lock. Internally, this operation is equivalent to calling ns_rwlock unlock.

ns_rwlock unlock rwlockid

Unlocks the rwlock rwlockid regardless of whether it is a read or write lock.

ns_rwlock writeeval rwlockid script

A convenience function to lock the specified rwlockid for writing, runs the script and then releases the lock. The command returns the result and any error condition of the executed script. If rwlockid does not exist, it will be auto-created, although this is generally not recommended.

ns_rwlock writelock rwlockid

Acquires a write lock. Only one write lock can be active at any given time. If there are active or pending read locks, the write lock acquisition will block until all read locks are released. Write locks take priority over subsequent read lock acquisition attempts.

ns_rwlock writeunlock rwlockid

Releases a write lock. Internally, this operation is equivalent to calling ns_rwlock unlock.

EXAMPLES

Basic Read Lock:

 set rwlockid [ns_rwlock create]
 ns_rwlock readlock $rwlockid
 # Perform read-only operations here
 ns_rwlock readunlock $rwlockid

Running a script under a Read Lock:

 set result [ns_rwlock readeval $rwlockid {
    # Read-only operations
    return "Read operation result"
 }]

Basic Write Lock:

 set rwlockid [ns_rwlock create]
 ns_rwlock writelock $rwlockid
 # Perform write operations here
 ns_rwlock writeunlock $rwlockid

Running a script under a Write Lock:

 set result [ns_rwlock writeeval $rwlockid {
    # Write operations
    return "Write operation result"
 }]

NOTES

About Read/Write Locks

Read/write locks are a synchronization mechanism designed for scenarios where multiple threads need to read shared data simultaneously, but only one thread should modify the data at a time. This allows efficient concurrent reads while ensuring data consistency during writes.

Priority Rules:

  1. Read locks: Multiple read locks can be acquired simultaneously without blocking. However, they will block if a write lock is active.

  2. Write locks: Only one write lock can be active at a time. A write lock will wait for any active read locks to be released and will block any new read locks until it completes. Write locks take precedence over pending read locks.

Use Case Example: A heavily accessed hash table that is read frequently but updated infrequently can benefit from read/write locks. This allows multiple threads to read from the table concurrently, while updates are safely managed by blocking until the current read operations complete and preventing new reads during the update.

See Also

ns_cond, ns_critsec, ns_mutex, ns_sema, ns_thread

Keywords

concurrency, rwlock, server built-in, synchronization, threading