3 namespace "urn:opendaylight:params:xml:ns:yang:programming";
6 import ietf-inet-types { prefix inet; revision-date 2013-07-15; }
8 organization "Cisco Systems, Inc.";
9 contact "Robert Varga <rovarga@cisco.com>";
12 "This module contains the basic programming model.
14 From the architecture perspective, the programming model is
15 used to drive the state of the controller and, by extension,
16 its underlying network from one state to another, usually
17 through some interim states.
19 The core concept of this model is that of an instruction. An
20 instruction is always an atomic, undivisible amount of work,
21 resulting in a well-defined state transition. More complex
22 state transitions are always broken up to a set of such
23 instructions. As a general rule, instructions should be
24 designed such that their implementations can guarantee them
25 either happening completely or not happening at all.
27 Instruction scheduling is governed by explicit dependencies,
28 where an instruction may only be a candidate for execution if
29 all of its dependencies have completed successfully. If there
30 are multiple candidate instructions, the scheduler is free
31 to decide on the order of execution, it may even execute them
32 in parallel. If two instructions become candidates and cannot
33 be executed in parallel, the scheduler should execute them in
34 the order in which they have been submitted.
36 The programming model does not rely on rollback capability
37 being present in the network. Instead it recognizes that this
38 failure results in a new state, which needs to be picked up
39 by the entity driving the change and a new set of state
40 transitions needs to be devised. Technology-specific modules
41 should rely on this assumption and should not attempt complex
42 recovery schemes, which could result in more indeterminism
43 being introduced in the state.
45 The final assumption of the model is that each instruction has
46 a specific deadline by which it needs to complete. The rationale
47 is that the entity driving the state has to make some progress
48 and not be stuck indefinitely on one transition. Furthermore
49 the model assumes the realization that there is a failure in
50 making progress in the scheduler, such that the instruction
51 stream can be predictably cut without introducing new race
52 windows in the recovery path.
54 A summary of the model is the following: the scheduler operates
55 on a directed acyclic graph of instructions which places limits
56 on which interim states may be visited while the system
57 transitions from a state measured at a point in time into the
58 intended state. The graph may be expanded to include new nodes,
59 allowing for futher submissions in a manner consistent with
60 optimistic prediction of future state.
62 Copyright (c)2013 Cisco Systems, Inc. All rights reserved.
64 This program and the accompanying materials are made available
65 under the terms of the Eclipse Public License v1.0 which
66 accompanies this distribution, and is available at
67 http://www.eclipse.org/legal/epl-v10.html";
69 revision "2015-07-20" {
71 "Introduce instruction queue id.";
74 revision "2013-09-30" {
82 "Absolute number of nanoseconds since the start of the
88 typedef instruction-id {
90 "Instruction identifier. It is assigned by the entity
91 generating the instruction and is required to be unique
92 during the lifetime of the instruction.";
96 typedef instruction-status {
98 "Each instruction submitted to the scheduler undergoes
99 a lifecycle with the distinct states defined by this
100 enumeration. The instruction starts in queued state
101 and progresses from there to one of the terminal
102 states: cancelled, failed or successful.";
107 "Its immediate prerequisite intructions
108 have not been resolved. The instruction
109 can be cancelled. If any of its
110 prerequisites moves to Unknown, Failed or
111 Cancelled state, the instruction itself
112 moves into Cancelled state. Once all of
113 the dependencies move into Successful
114 state, this instruction moves into
115 Scheduled state. If this instruction's
116 deadline passes, it transitions into
121 "All of instruction's prerequisites have
122 been successful and this instruction is
123 ready to be executed, but the resources
124 needed for its execution are not ready.
125 The instruction can be Cancelled. If this
126 instruction's deadline passes, it
127 transitions into Failed state.";
131 "The instruction is being executed. It
132 cannot be Cancelled on request. If the
133 execution does not complete within the
134 specified deadline, this instruction
135 moves into Unknown state. If the
136 instruction's execution completes within
137 the deadline, it moves into Successful,
138 Failed or Cancelled state, based on the
139 effects it has had on state.";
143 "The instruction has never executed, or
144 has been executing but all its effects
145 have been rolled back. System state is
146 such as if the instruction never
151 "The instruciton has failed to execute
152 completely, but some of its effects may
153 have been recorded in the state. A full
154 state resynchronization is required to
155 recover from this failure, and even then
156 an operator intervention may be required
157 (if, for example the effect is not
158 representable in exposed abstractions).";
162 "The instruction has executed competely
163 and its effects have been recorded in
168 "The instruction has failed to execute
169 within the deadline allocated to it.
170 It's effects on the state are unknown
171 at this point, but can be assumed to
172 either atomically happen or not-happen.
173 This state is transient and the
174 instruction will eventually (at some
175 indeterminate point in the future) enter
176 either Successful, Failed or Cancelled
182 grouping instruction-queue {
184 "The bare minimum run-time information which should be
185 exposed by an implementation of the instruction
186 scheduler defined in this model";
188 leaf instruction-queue-id {
194 "List of all instructions known to the
204 type instruction-status;
215 identity cancel-failure {
217 "The base identity of various reasons for an
218 instruction cancellation to fail.";
221 identity unknown-instruction {
223 "The specified instruction ID has not been found
228 identity uncancellable-instruction {
230 "The specified instruction is in process of being
231 executed and cannot be cancelled. Wait for the
232 execution process to complete.";
236 rpc cancel-instruction {
253 rpc clean-instructions {
255 "Attempt to clean out a certain set of instructions.
256 Instructions flushed this way need to be in a terminal
257 state, e.g. Successful, Failed or Cancelled. Instructions
258 which were not cleaned are reported in the output of
268 leaf-list unflushed {
274 identity submit-failure {
276 "The base identity of various reasons for an
277 instruction submission to fail.";
280 identity duplicate-instruction-id {
282 "Instruction ID clashes with an instruction with an
283 already-queued instruction. Assign a new identifier
284 or wait for the enqueued instruction to complete.";
288 identity too-many-instructions {
290 "Instruction queue size exceeded.";
294 identity unknown-precondition-id {
296 "One of the instruction IDs specified in the
297 precondition list is unknown.";
301 identity dead-on-arrival {
303 "The instruction was submitted after its deadline has
304 passed, or one of its dependencies resolved as
309 grouping submit-instruction-input {
311 "Minimum required arguments needed for submitting an
312 instruction into the scheduler. This grouping needs to
313 be used by concrete RPC definitions which are routed
326 leaf-list preconditions {
331 grouping submit-instruction-output {
342 leaf-list failed-preconditions {
343 when "../type = dead-on-arrival";
351 list instructions-queue {
352 key "instruction-queue-id";
353 uses instruction-queue;
356 notification instruction-status-changed {
358 description "Instruction identifier.";
364 description "New status of the instruction.";
365 type instruction-status;
371 "More details about the instruction state.";
373 leaf-list unmet-dependencies {
374 when "../../status = cancelled";