rvm_set_range(3)

NAME
rvm_set_range - define a modification range

SYNOPSIS

#include "rvm.h"
rvm_return_t rvm_set_range (tid,dest,length)
rvm_tid_t      *tid;   /* pointer to transaction identifier */
char           *dest;  /* base address of modification range */
unsigned long  length; /* length of range in bytes */

DESCRIPTION
rvm_set_range defines a modification range within a transaction. The transaction must have been begun with rvm_begin_transaction, or the RVM_ETID exception code is returned. The range is specified with the dest and length parameters, and must be in valid virtual memory or RVM_ERANGE is returned. The range must also be within a single mapped region or RVM_ENOT_MAPPED is returned. A range of zero length is ignored. Range modifications provide efficient logging for transactions modifying memory in a specific range, and is ideal when modifications are not sparse. The original values within the range are preserved for possible restoration upon transaction abort. eliminating the need for a modify operator to log changes as they are made so normal assignment statements can be used. Changes can be made anywhere in the range and need not be sequential. A common programming error is to make modifications without doing a rvm_set_range call to declare the modifications to RVM. This results in changes that are not permanent: since RVM has not been informed of the changes, it cannot log the new values and the changes are lost when the region is unmapped or if a crash occurs. The declaration of a modification range should always be made before the modifications are actually assigned. This is absolutely required if the transaction was begun in restore mode, since the old values cannot be recorded otherwise and will not be available for restoration upon transaction abort. In future versions, making modifications before calling rvm_set_range may result in incorrect operation. rvm_set_range can be used as many times as necessary within a transaction to define the ranges of modifications required. rvm_set_range and rvm_modify_bytes are not mutually exclusive, and can be used in the same transaction as is convenient to the programmer. If the transaction was begun with the no_restore mode, no old value record will be created for the modification range, and an abort will not restore the state of virtual memory. If memory to create an old value record for the range cannot be allocated, RVM_ENO_MEMORY is returned.

DIAGNOSTICS

RVM_SUCCESS
    success

RVM_ETID
    invalid transaction identifier or pointer

RVM_ERANGE
    invalide virtual memory range

RVM_ENOT_MAPPED
    virtual memory range not mapped

RVM_ENO_MEMORY
    heap exhausted

RVM_EINIT
    RVM not initialized

SEE ALSO
rvm_begin_transaction (3), rvm_modify_bytes (3), rvm_end_transaction (3), and rvm_abort_transaction (3)

AUTHOR
Hank Mashburn

BUGS
A range cannot extend across a region boundary even if virtual memory is contiguously mapped.