X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=ovsdb%2FSPECS;h=5bdb9741de225ce3419f948f7ca2c1d8bf6043d4;hb=ff71b4aa99b6d7305340d1b588c18cfd01b9a9de;hp=d64812ae6589fdb2fcd6ee09d8f677d225adc1ae;hpb=d198c4beee03741670d046baf0179ac5583305bb;p=sliver-openvswitch.git diff --git a/ovsdb/SPECS b/ovsdb/SPECS index d64812ae6..5bdb9741d 100644 --- a/ovsdb/SPECS +++ b/ovsdb/SPECS @@ -131,6 +131,8 @@ is represented by , as described below. "columns": {: , ...} required "maxRows": optional + "isRoot": optional + "indexes": [*] optional The value of "columns" is a JSON object whose names are column names and whose values are s. @@ -152,12 +154,37 @@ is represented by , as described below. the database process is stopped and then started again, each "_version" also changes to a new random value. + If "isRoot" is omitted or specified as false, then any given row + in the table may exist only when there is at least one reference + to it, with refType "strong", from a different row (in the same + table or a different table). This is a "deferred" action: + unreferenced rows in the table are deleted just before transaction + commit. If "isRoot" is specified as true, then rows in the table + exist independent of any references (they can be thought of as + part of the "root set" in a garbage collector). + + For compatibility with schemas created before "isRoot" was + introduced, if "isRoot" is omitted or false in every + in a given , then every table is + part of the root set. + If "maxRows" is specified, as a positive integer, it limits the maximum number of rows that may be present in the table. This is a "deferred" constraint, enforced only at transaction commit time (see the "transact" request below). If "maxRows" is not specified, the size of the table is limited only by the resources - available to the database server. + available to the database server. "maxRows" constraints are + enforced after unreferenced rows are deleted from tables with a + false "isRoot". + + If "indexes" is specified, it must be an array of zero or more + s. A is an array of one or more strings, + each of which names a column. Each is a set of + columns whose values, taken together within any given row, must be + unique within the table. This is a "deferred" constraint, + enforced only at transaction commit time, after unreferenced rows + are deleted and dangling weak references are removed. Ephemeral + columns may not be part of indexes. @@ -167,12 +194,18 @@ is represented by , as described below. "ephemeral": optional "mutable": optional - The "type" specifies the type of data stored in this column. If - "ephemeral" is specified as true, then this column's values are + The "type" specifies the type of data stored in this column. + + If "ephemeral" is specified as true, then this column's values are not guaranteed to be durable; they may be lost when the database - restarts. If "mutable" is specified as false, then this column's - values may not be modified after they are initially set with the - "insert" operation. + restarts. A column whose type (either key or value) is a strong + reference to a table that is not part of the root set is always + durable, regardless of this value. (Otherwise, restarting the + database could lose entire rows.) + + If "mutable" is specified as false, then this column's values may + not be modified after they are initially set with the "insert" + operation. @@ -409,6 +442,16 @@ include at least the following: The number of rows in a table exceeds the maximum number permitted by the table's "maxRows" value (see ). + "error": "constraint violation" + + Two or more rows in a table had the same values in the columns + that comprise an index. + + "error": "resources exhausted" + "error": "I/O error" + + As described in the definition of above. + If "params" contains one or more "wait" operations, then the transaction may take an arbitrary amount of time to complete. The database implementation must be capable of accepting, executing, and @@ -584,6 +627,107 @@ Cancels the ongoing table monitor request, identified by the ongoing "monitor" request. No more "update" messages will be sent for this table monitor. +lock operations +............... + +Request object members: + + "method": "lock", "steal", or "unlock" required + "params": [] required + "id": required + +Response object members: + + "result": {"locked": } for "lock" + "result": {"locked": true} for "steal" + "result": {} for "unlock" + "error": null + "id": same "id" as request + +Performs an operation on a "lock" object. The database server +supports an arbitrary number of locks, each of which is identified by +a client-defined id (given in "params"). At any given time, each lock +may have at most one owner. + +The locking operation depends on "method": + + - "lock": The database will assign this client ownership of the + lock as soon as it becomes available. When multiple clients + request the same lock, they will receive it in first-come, first + served order. + + - "steal": The database immediately assigns this client ownership + of the lock. If there is an existing owner, it loses ownership. + + - "unlock": If the client owns the lock, releases it. If the + client is waiting to obtain the lock, cancels the request and + stops waiting. + + (Closing or otherwise disconnecting a database client connection + unlocks all of its locks.) + +For any given lock, the client must alternate "lock" or "steal" +operations with "unlock" operations. That is, if the previous +operation on a lock was "lock" or "steal", it must be followed by an +"unlock" operation, and vice versa. + +For a "lock" operation, the "locked" member in the response object is +true if the lock has already been acquired, false if another client +holds the lock and the client's request for it was queued. In the +latter case, the client will be notified later with a "locked" message +when acquisition succeeds. + +These requests complete and send a response quickly, without waiting. +The "locked" and "stolen" notifications (see below) report +asynchronous changes to ownership. + +The scope of a lock is a database server, not a database hosted by +that server. A naming convention, such as "__", +can effectively limit the scope of a lock to a particular database. + +locked +...... + +Notification object members: + + "method": "locked" + "params": [] + "id": null + +Notifies the client that a "lock" operation that it previously +requested has succeeded. The client now owns the lock named in +"params". + +The database server sends this notification after the reply to the +corresponding "lock" request (but only if the "locked" member of the +response was false), and before the reply to the client's subsequent +"unlock" request. + +stolen +...... + +Notification object members: + + "method": "stolen" + "params": [] + "id": null + +Notifies the client that owns a lock that another database client has +stolen ownership of the lock. The client no longer owns the lock +named in "params". The client must still issue an "unlock" request +before performing any subsequent "lock" or "steal" operation on the +lock. + +If the client originally obtained the lock through a "lock" request, +then it will automatically regain the lock later after the client that +stole it releases it. (The database server will send the client a +"locked" notification at that point to let it know.) + +If the client originally obtained the lock through a "steal" request, +the database server won't automatically reassign it ownership of the +lock when it later becomes available. To regain ownership, the client +must "unlock" and then "lock" or "steal" the lock again. + echo .... @@ -1149,3 +1293,26 @@ Semantics: Provides information to a database administrator on the purpose of a transaction. The OVSDB server, for example, adds comments in transactions that modify the database to the database journal. + +assert +...... + +Request object members: + + "op": "assert" required + "lock": required + +Result object members: + + none + +Semantics: + + If the client does not own the lock named , aborts the + transaction. + +Errors: + + "error": "not owner" + + The client does not own the named lock.