ACE/examples/Bounded_Packet_Relay/README

   1
   2
   3 1. INTRODUCTION
   4
   5 This directory contains an example that illustrates how to use both
   6 threaded and reactive concurrency mechanisms in ACE.  The example
   7 application schedules and processes heterogenerous user input and
   8 timer-based events in the context of a bounded packet relay mechanism.
   9
  10 In this example, a transmission begins, packets arrive from an input device
  11 object, and are transferred to an output device object by a relay object at
  12 a specified pace.  The transfer continues until all packets have been
  13 relayed, a duration limit expires, or the transmission is cancelled.
  14
  15 User input is handled concurrently with a running transmission.  You
  16 can run a transmission, cancel a transmission, change transmission
  17 parameters, view statistics from the most recent transmission, or exit
  18 the program, using selections from an interactive text-based menu.
  19 In addition, the example program can be run in batch mode, with the
  20 appropriate commands piped to the program's standard input stream.
  21
  22 Transmission parameters are intialized to default values.  Transmission
  23 parameter values persist until/unless they are subsequently modified by an
  24 appropriate command.  If an invalid value for a command is given, or a run
  25 or report command is issued while a transmission is in progress, the
  26 offending command has no effect, and an error message is generated.
  27
  28 2. USER INTERFACE
  29
  30 Commands that can be given to the program include the following:
  31
  32 Settings commands:
  33
  34   1 <number of packets to relay in one transmission>
  35
  36      Minimum value is 1 packet, defaults to 1000 packets.
  37
  38   2 <input packet arrival period (in usec)>
  39
  40      Minimum value is 1 usec, defaults to 10000 usec (10 msec).
  41
  42   3 <output packet transmission period (in usec)>
  43
  44      Minimum value is 1 usec, defaults to 10000 usec (10 msec).
  45
  46   4 <limit on duration of transmission (in usec)>
  47
  48      Minimum value is 1 usec, defaults to 20000000 usec (20 sec).
  49      A value of 0 is also a valid input, in which case no limit
  50      will be placed on the duration of the transmission (it will
  51      end when all packets have been relayed from the input device
  52      to the output device).
  53
  54   5 <logging level>
  55
  56      0 - does no logging
  57      1 - logs packets created by the input device
  58      2 - logs packets consumed by the output device
  59      4 - prints contents of packets consumed by the output device
  60
  61      To set several flags, pass their sum as the logging level value:
  62      e.g., a logging level value of 7 turns on all possible logging.
  63
  64 Action commands:
  65
  66   6 - runs a transmission using the current settings
  67
  68   7 - cancels a transmission if there is one running
  69
  70   8 - reports statistics from the most recent transmission
  71
  72   9 - quits the program
  73
  74 3. APPLICATION DESIGN
  75
  76 3.1. KEY COMPONENTS
  77
  78 The design of this example application consists of four main
  79 components: the driver object, the relay object, the input device
  80 object, and the output device object.
  81
  82 The driver object is responsible for receiving user input and overall handling
  83 of user input commands.  The driver object is active, with separate threads
  84 for receiving user input and managing its transmission timer queue.  This
  85 allows the user to issue commands while a transmission is in progress.  The
  86 driver object uses an ACE_Thread_Timer_Queue_Adapter, which is derived from
  87 ACE_Task_Base.  The driver object starts another active object, called
  88 User_Input_Task, which is also derived from ACE_Task_Base.  This allows both
  89 the timer queue and the user input object to be made active, running in their
  90 own threads of control.
  91
  92 The relay object is passive, managing a message queue and necessary
  93 locks to allow safe access from multiple threads.  It provides methods
  94 to receive and enqueue a mesage from the input device, dequeue a
  95 message and send it to the output device, and to start or end a
  96 transmission.  It uses ACE_Message_Queue (which contains ACE_Message_Block
  97 objects) and ACE_Thread_Mutex objects to implement this functionality.
  98
  99 The input object is active, managing timeouts and input events in its
 100 own thread.  The input object is also reactive, using an ACE_Reactor to
 101 allow response to multiple input handles as well as to do polling at
 102 specific timeouts.  The input pseudo-device wrapper in this example
 103 does not make use of input handles and only does timed polling, but
 104 extending this only requires registering the appropriate input handles
 105 and handlers with the reactor.  The input object is derived from
 106 ACE_Task_Base, and is activated by the relay object when a new
 107 transmission starts.  The input object packages each data packet in an
 108 ACE_Message_Block before sending it to the relay object.
 109
 110 The output object is passive.  If logging is turned on, it will report
 111 the arrival time, relative to the start of the transmission, of each
 112 output message, and the contents of that message.  The output object
 113 will also "consume" each ACE_Message_Block passed to it, calling
 114 delete on the passed pointer.
 115
 116 3.2. RUN-TIME CHARACTERSITICS
 117
 118 When the user initiates a transmission, the appropriate settings are passed
 119 by the driver to the relay object's start transmission method. The relay
 120 object tries to start a new transmission.  If another transmission is in
 121 progress, the method returns an error.  Otherwise, the relay object's start
 122 transmission method initializes itself and the input and output device
 123 objects, activates the input device object, and stores the handle for
 124 the new input device thread.
 125
 126 The driver then constructs a timeout handler with a count of the
 127 number of messages to relay and a send timeout value, and pushes a
 128 timer with this handler onto the timer queue.  If there is a limit on
 129 the duration of the transmission, the driver constructs a different
 130 handler for end-of-transmission, and pushes a timer for the end of
 131 the transmission with this handler onto the timer queue as well.  When
 132 the user issues a cancel transmission command, the driver calls the
 133 relay's end transmission method.
 134
 135 When a send timeout expires, the handler (running in the timer queue
 136 thread) calls the send method of the relay.  If there are any enqueued
 137 messages from the input device object in its queue, the relay object's
 138 send method will dequeue a message, pass it to the output device
 139 object, and return success.  If there are no messages in the queue,
 140 the relay object's send method will return failure.  If the send was
 141 successful, the handler will decrement its count of remaining
 142 messages.  If the count is greater than zero, the handler will
 143 register a new send timer for itself and exit.  If the count is zero,
 144 then the handler will call the relay's end transmission method, clear
 145 the timer queue, and mark itself inactive before exiting.
 146
 147 Similarly, if the end-of-transmission timer expires before all packets
 148 have been sent, that handler will call the relay's end transmission
 149 method, clear the timer queue, release the semaphore, and then exit.
 150
 151 When the relay's end transmission method is called, it marks the relay
 152 itself inactive, and calls the input device's deactivate method, which
 153 sets the input device's activity flag to inactive (see below).  The
 154 relay's end transmission method then waits until the input device thread
 155 exits, before returning.
 156
 157 While it is still active, the input device thread blocks on a reactor
 158 timeout for the duration it was given by the relay.  When the timeout
 159 expires, the input device checks a flag to see if it is still active.
 160 If the flag says the input device is inactive, the thread simply
 161 exits.  This allows cancellation of the input device when a
 162 transmission has ended.  If the flag says it is still active, the
 163 thread builds a new character buffer, and wraps this with a new
 164 ACE_Message_Block.  The input device passes this message block to the
 165 execution method of the send input message command object with which
 166 it was constructed. This level of indirection allows the input device
 167 to be used with arbitrary types, so that it could for example be
 168 connected directly to an output device.  The input device also
 169 maintains a count of the number of messages it has sent.  Once the
 170 input device has sent all its messages, it marks itself inactive, and
 171 its thread simply exits.
 172
 173 4. ACCESSING THE SOURCE CODE
 174
 175 The files for this example are located in
 176 $ACE_ROOT/examples/Bounded_Packet_Relay in the latest release of ACE,
 177 which is located at
 178
 179 https://github.com/DOCGroup/ACE_TAO
 180
 181 Source Files: Thread_Bounded_Packet_Relay.h
 182               Thread_Bounded_Packet_Relay.cpp
 183               BPR_Driver.h
 184               BPR_Driver.cpp
 185               BPR_Driver_T.h
 186               BPR_Driver_T.cpp
 187               bpr_thread.cpp
 188
 189 Make file:    Makefile
 190
 191 Doc file:     README (this file)
 192
 193 Executable:   bpr_thread
 194
 195
 196