LEFT | RIGHT |
(no file at all) | |
| 1 .. include:: replace.txt |
| 2 .. highlight:: cpp |
| 3 |
| 4 .. _Start-stop-functionality: |
| 5 |
| 6 Start and Stop Functionality |
| 7 ---------------------------- |
| 8 |
| 9 :cpp:class:`StartStopFunctionality` implements functions :cpp:func:`Start` and |
| 10 :cpp:func:`Stop`, that are used for starting and stopping an |
| 11 :cpp:class:`Object`. It is intended to be used as a mixin for subclasses of |
| 12 :cpp:class:`Object` class that only require basic Start and Stop functionality. |
| 13 For example, one can consider hypothetical class |
| 14 :cpp:class:`SimplePointToPointChannel` that would model a very simple |
| 15 point-to-point channel transmitting packets and be a subclass of |
| 16 :cpp:class:`Channel` class, which is in turn subclass of :cpp:class:`Object`. |
| 17 One can take the started state to mean channel transmitting packets as expected, |
| 18 and stopped state to mean channel not transmitting anything. |
| 19 :cpp:class:`SimplePointToPointChannel` class could be implemented as:: |
| 20 |
| 21 class SimplePointToPointChannel : public Channel, public StartStopFunctionalit
y |
| 22 { |
| 23 // declaration of class functions |
| 24 ... |
| 25 } |
| 26 |
| 27 While the behavior of an object in started and stopped state depends on |
| 28 properties of the model, there are some general guidelines about implementation |
| 29 of this functionality by classes using :cpp:class:`StartStopFunctionality` |
| 30 mixin. Specifically, they should do the following. |
| 31 |
| 32 Classes using :cpp:class:`StartStopFunctionality` should check object state |
| 33 using :cpp:func:`IsStarted` function. In this case one could write the code of |
| 34 a hypotetical :cpp:func:`Transmit` function as:: |
| 35 |
| 36 void |
| 37 SimplePointToPointChannel::Transmit (Ptr<Packet> packet) |
| 38 { |
| 39 if (IsStarted ()) |
| 40 { |
| 41 // schedule packet Rx |
| 42 ... |
| 43 } |
| 44 else |
| 45 { |
| 46 NS_LOG_INFO ("Simple point-to-point channel " << this << " is not started,
packet is not being sent"); |
| 47 // do nothing or possibly trigger packet drop trace |
| 48 } |
| 49 } |
| 50 |
| 51 Classes using :cpp:class:`StartStopFunctionality` should implement specific |
| 52 start and stop operation by overriding virtual :cpp:func:`Start` and |
| 53 :cpp:func:`Stop` functions, and chaining up to parent class's implementation of |
| 54 these. For example, considering :cpp:class:`SimplePointToPointChannel` again, |
| 55 one could do the following:: |
| 56 |
| 57 void |
| 58 SimplePointToPointChannel::Start () |
| 59 { |
| 60 // notify devices channel is now started |
| 61 ... |
| 62 StartStopFunctionality::Start (); |
| 63 } |
| 64 |
| 65 void |
| 66 SimplePointToPointChannel::Stop () |
| 67 { |
| 68 // stop transmission if in progress |
| 69 ... |
| 70 SimplePointToPointChannel::Stop (); |
| 71 } |
| 72 |
| 73 Classes using :cpp:class:`StartStopFunctionality` should not override or |
| 74 reimplement :cpp:func:`Start` and :cpp:func:`Stop` functions. If they desire to |
| 75 do so, :cpp:class:`StartStopFunctionality` should not be used and functionality |
| 76 should be implemented independently. :cpp:class:`FailureRepairModel` class does |
| 77 not require usage of :cpp:class:`StartStopFunctionality`. |
| 78 |
| 79 Note that calling :cpp:func:`Start` or :cpp:func:`Stop` on an object does not |
| 80 affect aggregated objects. Users who have the requirement to start and stop |
| 81 object along with aggregates should implement such functionality independently. |
LEFT | RIGHT |