X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=9fd654be6d1c51857ed0d5932adf47bfd6a4440b;hb=e9f8f9367e9e654b9582279608af86ea3744a2a0;hp=17b0840cacc7706790be4c8f94a9fb07e1cadf9d;hpb=12996ef9bc757c4f86dc298e4680541527e5ed81;p=openvswitch

diff --git a/ovsdb/SPECS b/ovsdb/SPECS
index 17b0840c..9fd654be 100644
--- a/ovsdb/SPECS
+++ b/ovsdb/SPECS
@@ -586,6 +586,79 @@ Notation for the Wire Protocol
 
     One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
 
+<mutation>
+
+    A 3-element JSON array of the form [<column>, <mutator>, <value>]
+    that represents a change to a column value.
+
+    Except as otherwise specified below, <value> must have the same
+    type as <column>.
+
+    The meaning depends on the type of <column>:
+
+        integer
+        real
+
+            <mutator> must be "+=", "-=", "*=", "/=" or (integer only)
+            "%=".  The value of <column> is changed to the sum,
+            difference, product, quotient, or remainder, respectively,
+            of <column> and <value>.
+
+        boolean
+        string
+        uuid
+
+            No valid <mutator>s are currently defined for these types.
+
+        set
+
+            Any <mutator> valid for the set's element type may be
+            applied to the set, in which case the mutation is applied
+            to each member of the set individually.  <value> must be a
+            scalar value of the same type as the set's element type.
+
+            If <mutator> is "insert", then each of the values in the
+            set in <value> is added to <column> if it is not already
+            present.  The required type of <value> is slightly
+            relaxed, in that it may have fewer than the minimum number
+            of elements specified by the column's type.
+
+            If <mutator> is "delete", then each of the values in the
+            set in <value> is removed from <column> if it is present
+            there.  The required type is slightly relaxed in that
+            <value> may have more or less than the maximum number of
+            elements specified by the column's type.
+
+        map
+
+            <mutator> must be "insert" or "delete".
+
+            If <mutator> is "insert", then each of the key-value pairs
+            in the map in <value> is added to <column> if its key is
+            not already present.  The required type of <value> is
+            slightly relaxed, in that it may have fewer than the
+            minimum number of elements specified by the column's type.
+
+            If <mutator> is "delete", then <value> may have the same
+            type as <column> (a map type) or it may be a set whose
+            element type is the same as <column>'s key type:
+
+                - If <value> is a map, the mutation deletes each
+                  key-value pair in <column> whose key and value equal
+                  one of the key-value pairs in <value>.
+
+                - If <value> is a set, the mutation deletes each
+                  key-value pair in <column> whose key equals one of
+                  the values in <value>.
+
+            For "delete", <value> may have any number of elements,
+            regardless of restrictions on the number of elements in
+            <column>.
+
+<mutator>
+
+    One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".
+
 Operations
 ----------
 
@@ -599,7 +672,7 @@ Request object members:
     "op": "insert"          required
     "table": <table>        required
     "row": <row>            required
-    "uuid-name": <string>   optional
+    "uuid-name": <id>       optional
 
 Result object members:
 
@@ -611,10 +684,31 @@ Semantics:
     for all the columns in "table", those columns receive default
     values.
 
-    The new row receives a new, randomly generated UUID, which is
-    returned as the "uuid" member of the result.  If "uuid-name" is
-    supplied, then the UUID is made available under that name to this
-    operation and later operations within the same transaction.
+    If "uuid-name" is not supplied, the new row receives a new,
+    randomly generated UUID.
+
+    If "uuid-name" is supplied, then it is an error if <id> has
+    previously appeared as the "uuid-name" in an "insert" operation.
+
+    If "uuid-name" is supplied and its <id> previously appeared as the
+    "uuid-name" in a "declare" operation, then the new row receives
+    the UUID associated with that "uuid-name".
+
+    If "uuid-name" is supplied and its <id> has not previously
+    appeared as the "uuid-name" in a "declare" operation, then the new
+    row also receives a new, randomly generated UUID.  This UUID is
+    also made available under that name to this operation and later
+    operations within the same transaction.
+
+    The UUID for the new row is returned as the "uuid" member of the
+    result.
+
+Errors:
+
+    "error": "duplicate uuid-name"
+
+        The same "uuid-name" appeared on an earlier "insert" operation
+        within this transaction.
 
 select
 ......
@@ -678,6 +772,57 @@ Semantics:
     The "count" member of the result specifies the number of rows
     that matched.
 
+mutate
+......
+
+Request object members:
+
+    "op": "mutate"                required
+    "table": <table>              required
+    "where": [<condition>*]       required
+    "mutations": [<mutation>*]    required
+
+Result object members:
+
+    "count": <integer>
+
+Semantics:
+
+    Mutates rows in a table.
+
+    Searches "table" for rows that match all the conditions specified
+    in "where".  For each matching row, mutates its columns as
+    specified by each <mutation> in "mutations", in the order
+    specified.
+
+    The "_uuid" and "_version" columns of a table may not be directly
+    modified with this operation.  Columns designated read-only in the
+    schema also may not be updated.
+
+    The "count" member of the result specifies the number of rows
+    that matched.
+
+Errors:
+
+    "error": "domain error"
+
+        The result of the mutation is not mathematically defined,
+        e.g. division by zero.
+
+    "error": "range error"
+
+        The result of the mutation is not representable within the
+        database's format, e.g. an integer result outside the range
+        INT64_MIN...INT64_MAX or a real result outside the range
+        -DBL_MAX...DBL_MAX.
+
+    "error": "constraint violation"
+
+        The mutation caused the column's value to violate a
+        constraint, e.g. it caused a column to have more or fewer
+        values than are allowed or an arithmetic operation caused a
+        set or map to have duplicate elements.
+
 delete
 ......
 
@@ -797,3 +942,37 @@ Errors:
     "error": "aborted"
 
         This operation always fails with this error.
+
+declare
+.......
+
+Request object members:
+
+    "op": "declare"                    required
+    "uuid-name": <id>                  required
+
+Result object members:
+
+    none
+
+Semantics:
+
+    Predeclares a UUID named <id> that may be referenced in later
+    operations as ["named-uuid", <id>] or (at most once) in an
+    "insert" operation as "uuid-name".
+
+    It is an error if <id> has appeared as the "uuid-name" in a prior
+    "insert" or "declare" operation within this transaction.
+
+    The generated UUID is returned as the "uuid" member of the result.
+
+Result object members:
+
+    "uuid": <uuid>
+
+Errors:
+
+    "error": "duplicate uuid-name"
+
+        The same "uuid-name" appeared on an earlier "insert" or
+        "declare" operation within this transaction.