Put Operation for Storing a Tuple in a Space
To store a tuple in a space, call the space’s put method, which takes the tuple to put as an argument and returns what ever was overwritten in the space (if anything was) by the put.
The put operation is an “upsert” operation: like both the INSERT and UPDATE SQL statement (like a MERGE statement); it always overwrites what was stored previously in the space. When you perform a Put:
- If the tuple contains fields that do not match the names of the fields in the space's definition, then these fields are stripped from the tuple stored in the space
- If there is already a tuple containing a field with the same key field values stored the space at the time the put is invoked, then the old tuple is replaced by the new one. If this behavior is not desired, and you want to avoid overwriting an existing tuple by mistake, then you should use a special form of the space's update method.
- When the time the put is invoked, if there is already a matching tuple in the space and that tuple is locked, the method might block for the amount of time specified in the space definition’s LockWait attribute. After LockWait time is reached, if the stored tuple is still locked, the Put fails, and the failure scenario will be indicated by the Result object's Status field (or the return value of the method in C) having a value of LOCKED.
Specifying a LockWait Value for a Put
If you expect that the locks on tuples in the spaces will have a very short duration, ActiveSpaces allows you to specify a LockWait value for the space. The LockWait value is the number of milliseconds an operation attempting to modify a locked tuple can block while waiting for the lock to clear.
If at the end of the LockWait period, the tuple is still locked, then the operation to modify that locked tuple throws an exception indicating that the operation could not be performed because the tuple is locked. The LockWait value of a space is also taken into consideration if a member attempts a non-transacted operation that conflicts with uncommitted data (for example, tuples about to be replaced by uncommitted operations are locked by that transaction).
You can set or get the LockWait value by using the SpaceDef object’s setLockWait and getLockWait methods, respectively. Lock wait value is expressed in milliseconds. The default value is NO_WAIT, indicating that this feature is not used, and that an operation attempting to modify a locked tuple will immediately return with a failure indicating that the tuple is currently locked.