/core/externals/update-engine/Common/KSAction.h

  1// Copyright 2008 Google Inc.
  2//
  3// Licensed under the Apache License, Version 2.0 (the "License");
  4// you may not use this file except in compliance with the License.
  5// You may obtain a copy of the License at
  6//
  7//     http://www.apache.org/licenses/LICENSE-2.0
  8//
  9// Unless required by applicable law or agreed to in writing, software
 10// distributed under the License is distributed on an "AS IS" BASIS,
 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12// See the License for the specific language governing permissions and
 13// limitations under the License.
 14
 15#import <Foundation/Foundation.h>
 16
 17@class KSActionProcessor, KSActionPipe;
 18
 19// KSAction (Abstract)
 20//
 21// Abstract class that encapsulates a unit of work--an Action--to be performed.
 22// Examples of possible KSAction subclasses might be a "KSDownloadAction" or a
 23// "KSInstallAction", that each do the obvious thing that their name implies.
 24// Concrete KSAction instances are run by adding them to a KSActionProcessor's
 25// queue, then starting the KSActionProcessor. KSAction instances may perform
 26// their task synchronously or asynchronously. The only requirement is that they
 27// must tell their owning KSActionProcessor when they are finished by sending
 28// the KSActionProcessor a -finishedProcessing:successfully: message.
 29//
 30// When a KSAction is added to a KSActionProcessor, the KSActionProcessor will
 31// call -setProcessor: on the KSAction to indicate that the action is "owned" by
 32// the KSActionProcessor. Note that this happens when the action is enqueued,
 33// which may be significantly before the action is told to run. Also note that
 34// the by the time the action is told to run via the -performAction message, the
 35// -processor method is guaranteed to return a valid KSActionProcessor.
 36//
 37// Input-Output:
 38//
 39// Every KSAction has one KSActionPipe for input and one for output. These pipes
 40// are always present and are never nil. However, they can be replaced, and
 41// reset at any time. Action pipes are one way for actions to communicate with
 42// one another. One action may store its output in a KSActionPipe, and another
 43// action may use that same pipe for its input; thus connecting the two actions.
 44//
 45// KSActionPipes should be viewed as filling the same role as typical pipes on
 46// a Unix command line: connecting the output of one job to the input of
 47// another. This is true even though KSActionPipes are at a higher-level (an
 48// "object" level) than the stream-of-bytes level of typical Unix pipe(2)s.
 49//
 50// Subclassing:
 51//
 52// KSAction subclasses may be created and configured as necessary to enable them
 53// to perform their action. They should not actually perform their action until
 54// they are sent the -performAction message from a KSActionProcessor. If the
 55// action runs asynchronously, it should also implement the -terminateAction
 56// method, which should stop the action and only return once the action has been
 57// terminated. Subclasses will typically only need to override two methods:
 58// -performAction, and possibly, -terminateAction. The KSAction implementation
 59// of all other methods should be sufficient for nearly all KSAction subclasses.
 60//
 61// The lifecycle of a KSAction looks like the following:
 62//
 63//   1. KSAction is created like normal (e.g., alloc/init)
 64//   2. KSAction is added to a KSActionProcessor, at which point the KSAction
 65//      is sent a -setProcessor: message.
 66//   3. Eventually, the action is sent the -performAction message indicating
 67//      that the action should do its work
 68//   4. The action may or may not be sent a -terminateAction message indicating
 69//      that all work it is doing should be immediately stopped
 70//   5. Once the action completes successfully or otherwise, it is sent a
 71//      -setProcessor:nil message to indicate that it was removed from the
 72//      KSActionProcessor.
 73@interface KSAction : NSObject {
 74 @private
 75  KSActionProcessor *processor_;
 76  KSActionPipe *inpipe_;
 77  KSActionPipe *outpipe_;
 78}
 79
 80// Returns the KSActionProcessor instance that owns this KSAction.
 81- (KSActionProcessor *)processor;
 82
 83// Sets the KSActionProcessor that owns this KSAction. Note that a KSAction may
 84// only be in one KSActionProcessor at a time.
 85- (void)setProcessor:(KSActionProcessor *)processor;
 86
 87// Returns the KSActionPipe for this action to use for input. This method never
 88// returns nil.
 89- (KSActionPipe *)inPipe;
 90
 91// Sets the KSActionPipe for this action to use for input. If |inpipe| is nil,
 92// the input pipe will be re-set to a new, empty KSActionPipe.
 93- (void)setInPipe:(KSActionPipe *)inpipe;
 94
 95// Returns the KSActionPipe for this action to use for output. This method never
 96// returns nil.
 97- (KSActionPipe *)outPipe;
 98
 99// Sets the KSActionPipe for this action to use for output. If |outpipe| is nil,
100// the output pipe will be re-set to a new, empty KSActionPipe.
101- (void)setOutPipe:(KSActionPipe *)outpipe;
102
103// Returns YES if the action is currently running, NO otherwise. Subclasses
104// should NOT need to override this method. It returns YES if this action (self)
105// is the "current action" on its |processor|, NO otherwise. This should be the
106// correct "isRunning" status for the majority of KSAction subclasses.
107- (BOOL)isRunning;
108
109//
110// Methods that subclasses are likely to need to override.
111//
112
113// This message is sent by a KSActionProcessor when the action is supposed to
114// begin. This method may be synchronous or asynchronous. When the action is
115// complete, the -[KSActionProcessor finishedProcessing:successfully:] message
116// should be sent to the KSActionProcessor on which this action is running (as
117// obtained from the -processor message).
118//
119// Note that the -finishedProcessing:successfully: message should always be sent
120// to the processor instance eventually. This is the only way the processor
121// will know that the action has finished. The only caveat to this rule is if
122// your action is terminated by the -terminateAction method, then you should NOT
123// send -finishedProcessing:successfully: to the action processor.
124//
125// Also, keep in mind that, as with all Google code, this method is NOT allowed
126// to throw any exceptions. If you use an API that is documented to throw (or
127// is likely to throw), such as NSTask, it is your responsibility to catch that
128// and handle it appropriately.
129//
130// *** Note that a KSAction may only be on one KSActionProcessor at a time. ***
131- (void)performAction;
132
133// This message is sent by the KSActionProcessor when it needs to prematurely
134// terminate a running action. When this message is sent you should immediately
135// stop all processing before returning from this method.
136//
137// This method is optional. If your action doesn't need to do any cleanup, or
138// if it's synchronous (meaning, it will be done when -performAction
139// returns), this method does not need to be overridden.
140//
141// Subclasses should NOT send -finishedProcessing:successfully: to the action
142// processor from this method. If this method is called, the action processor
143// already knows that you're finishing, and therefore, it's unnecessary to
144// send that message.
145- (void)terminateAction;
146
147@end