[ Non-logical Variables, Arrays, Bags, Shelves and Stores | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# test_and_setval(+VarName, ?Old, ?New)

Test whether a non-logical variable has value Old and if so, set it to New.

VarName
  An atom
Old
  A term
New
  A term

## Description

VarName must be the name of a non-logical variable (not an array element and not a reference). If the current value of this variable is not identical to Old, the predicate fails. If it is identical, the variable's value gets changed to the value New. Test and set is done as an atomic operation.

### Modes and Determinism

- test_and_setval(+, ?, ?) is semidet

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

### Fail Conditions

Fails it the current value of the variable is not identical to Old

### Exceptions

(4) instantiation fault
  VarName is not ground
(5) type error
  VarName not an atom
(5) type error
  VarName is the name of a reference
(41) array or global variable does not exist
  VarName is not the name of a non-logical variable.

## Examples

    Success:
         ?- setval(k, 3), test_and_setval(k, 3, 5).

         wait_for_lock :-
    	    ( test_and_setval(lock, 0, 1) ->
    		true
    	    ;
    	        wait_for_lock
    	    ).

    Fail:
          setval(k, 1), test_and_setval(k, 3, 5).

## See Also

decval / 1, incval / 1, variable / 1, setval / 2, getval / 2