The os_file_lock class specifies a region of bytes in a file and is used to interface with the locking interface of os_file .

A process can request a read lock or a write lock for a specific file region. If the lock is granted, a read lock prevents other processes from obtaining a write lock for that region; a write lock prevents other processes from obtaining a read or a write lock for that region. If a process requests a lock that cannot be granted, the process blocks by default until the lock becomes available.

In the following example, a server process obtains a write lock on the first seven bytes of a file preventing the client process from obtaining a read lock on an overlapping six byte region.

Example <ospace/file/examples/lock1s.cpp>


  #include <iostream>
#include <ospace/file.h>

void
main()
  {
  os_file_toolkit initialize;

  os_file file
    (
    "lock1.txt",
    os_open_control::create_always,
    os_io_control::write_only_access
    );
  cout << "server: writes 0123456789" << endl;
  file.write( "0123456789", 10 );

  os_file_lock lock( os_file_lock::file_write_lock, 7 );// Lock 7 bytes from start.
  cout << "server: requests write lock" << endl;
  file.add_lock( lock );

  cout << "server: granted write lock" << endl;
  file.seek( 0 ); // Seek to start of file.
  cout << "server: writes MYWRITE" << endl;
  file.write( "MYWRITE", 7 ); // Overwrite first 7 bytes.

  cout << "server: sleeping for 5 seconds" << endl;
  ::sleep( 5 );
  cout << "server: awake" << endl;
  cout << "server: releases write lock" << endl;
  file.remove_lock( lock );
  }

Write 0123456789
server: requests write lock
server: granted write lock
server: writes MYWRITE
server: sleeping for 5 seconds

<pause>


  server: awake
server: releases write lock

Example <ospace/file/examples/lock1c.cpp>


  #include <iostream>
#include <ospace/file.h>

void
main()
  {
  os_file_toolkit initialize;

  os_file file( "lock1.txt" );
  os_file_lock lock( os_file_lock::file_read_lock, 6, 4 );

  cout << "client: requests read lock" << endl;
  file.add_lock( lock );

  cout << "client: granted read lock" << endl;
  file.seek( 4 );
  char buffer[ 7 ];
  file.read( buffer, 6 ); // Read 6 bytes from offset 4.
  buffer[ 6 ] = '\0';
  cout << "client: reads " << buffer << endl;
  cout << "client: releases read lock" << endl;
  file.remove_lock( lock );
  }

client: requests read lock

<delay>


  client: granted read lock
client: reads ITE789
client: releases read lock

You can request a non-blocking lock by passing false as the second parameter to add_lock() . The method add_lock() returns true if it obtains the lock.

The next client example is similar to the previous one; however, in this example, the client requests a non-blocking lock and this request continues in a loop until a lock is obtained.

Example <ospace/file/examples/lock2c.cpp>


  #include <iostream>
#include <ospace/file.h>

void
main()
  {
  os_file_toolkit initialize;

  os_file file( "lock1.txt" );
  os_file_lock lock( os_file_lock::file_read_lock, 6, 4 );

  while ( true )
    {
    cout << "client: requests read lock" << endl;
    if ( !file.add_lock( lock, false ) )
      {
      cout << "client: was not granted a read lock" << endl;
      ::sleep( 1 );
      }
    else
      {
      cout << "client: granted read lock" << endl;
      break;
      }
    }

  file.seek( 4 );
  char buffer[ 7 ];
  file.read( buffer, 6 );
  buffer[ 6 ] = '\0';
  cout << "client: reads " << buffer << endl;
  cout << "client: releases read lock" << endl;
  file.remove_lock( lock );
  }

client: requests read lock
client: was not granted a read lock
client: requests read lock
client: was not granted a read lock
client: requests read lock
client: was not granted a read lock
client: requests read lock
client: was not granted a read lock
client: requests read lock
client: granted read lock
client: reads ITE789
client: releases read lock