pkg/control/timer.go

   1 /*
   2 ==================================================================================
   3   Copyright (c) 2019 AT&T Intellectual Property.
   4   Copyright (c) 2019 Nokia
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 */
  19 /*
  20 Timer takes four parameters:
  21          1) strId                       string                          'string format timerMap key'
  22          2) nbrId                       int                             'numeric format timerMap key'
  23          3) timerDuration       time.Duration           'timer duration'
  24          4) tryCount        uint64              'tryCount'
  25          5) timerFunction       func(string, int)       'function to be executed when timer expires'
  26
  27         Timer function is put inside in-build time.AfterFunc() Go function, where it is run inside own Go routine
  28         when the timer expires. Timer are two key values. Both are used always, but the other one can be left
  29         "empty", i.e. strId = "" or  nbrId = 0. Fourth parameter is for tryCount. Fifth parameter, the timer
  30         function is bare function name without  any function parameters and parenthesis! Filling first parameter
  31         strId with related name can improve code readability and robustness, even the numeric Id would be enough
  32         from functionality point of view.
  33
  34         TimerStart() function starts the timer. If TimerStart() function is called again with same key values
  35         while earlier started timer is still in the timerMap, i.e. it has not been stopped or the timer has not
  36         yet expired, the old timer is deleted and new timer is started with the given time value.
  37
  38         StopTimer() function stops the timer. There is no need to call StopTimer() function after the timer has
  39         expired. Timer is removed automatically from the timeMap. Calling StopTimer() function with key values not
  40         existing in the timerMap, has no effect.
  41
  42         NOTE: Each timer is run in separate Go routine. Therefore, the function that is executed when timer expires
  43         MUST be designed to be able run concurrently! Also, function run order of simultaneously expired timers cannot
  44         guaranteed anyway!
  45
  46         If you need to transport more information to the timer function, consider to use another map to store the
  47         information with same key value, as the started timer.
  48
  49         Init timerMap example:
  50                 timerMap := new(TimerMap)
  51                 timerMap.Init()
  52
  53         StartTimer() and StartTimer() function usage examples.
  54         1)
  55                 subReqTime := 2 * time.Second
  56                 subId := 123
  57                 var tryCount uint64 = 1
  58                 timerMap.StartTimer("RIC_SUB_REQ", int(subId), subReqTime, FirstTry, handleSubscriptionRequestTimer)
  59                 timerMap.StopTimer("RIC_SUB_REQ", int(subId))
  60
  61
  62         StartTimer() retry example.
  63         2)
  64                 subReqTime := 2 * time.Second
  65                 subId := 123
  66                 var tryCount uint64 = 1
  67                 timerMap.StartTimer("RIC_SUB_REQ", int(subId), subReqTime, FirstTry, handleSubscriptionRequestTimer)
  68                 timerMap.StopTimer("RIC_SUB_REQ", int(subId))
  69
  70         3)
  71                 subReqTime := 2 * time.Second
  72                 strId := "1UHSUwNqxiVgUWXvC4zFaatpZFF"
  73                 var tryCount uint64 = 1
  74                 timerMap.StartTimer(strId, 0, subReqTime, FirstTry, handleSubscriptionRequestTimer)
  75                 timerMap.StopTimer(strId, 0)
  76
  77         4)
  78                 subReqTime := 2 * time.Second
  79                 strId := "1UHSUwNqxiVgUWXvC4zFaatpZFF"
  80                 var tryCount uint64 = 1
  81                 timerMap.StartTimer(RIC_SUB_REQ_" + strId, 0, subReqTime, FirstTry, handleSubscriptionRequestTimer)
  82                 timerMap.timerMap.StopTimer("RIC_SUB_REQ_" + strId, 0)
  83
  84         Timer function example. This is run if any of the above started timer expires.
  85                 func handleSubscriptionRequestTimer1(strId string, nbrId int, tryCount uint64) {
  86                         fmt.Printf("Subscription Request timer expired. Name: %v, SubId: %v, tryCount: %v\n",strId, nbrId, tryCount)
  87                         ...
  88
  89                         // Retry
  90                         ....
  91
  92                         tryCount++
  93                     timerMap.StartTimer("RIC_SUB_REQ", int(subId), subReqTime, tryCount, handleSubscriptionRequestTimer)
  94                         ...
  95
  96                 }
  97 */
  98
  99 package control
 100
 101 import (
 102         "gerrit.o-ran-sc.org/r/ric-plt/xapp-frame/pkg/xapp"
 103         "sync"
 104         "time"
 105 )
 106
 107 const FirstTry = 1
 108
 109 type TimerKey struct {
 110         strId string
 111         nbrId int
 112 }
 113
 114 type TimerInfo struct {
 115         timerAddress         *time.Timer
 116         timerFunctionAddress func()
 117 }
 118
 119 type TimerMap struct {
 120         timer map[TimerKey]TimerInfo
 121         mutex sync.Mutex
 122 }
 123
 124 // This method should run as a constructor
 125 func (t *TimerMap) Init() {
 126         t.timer = make(map[TimerKey]TimerInfo)
 127 }
 128
 129 func (t *TimerMap) StartTimer(strId string, nbrId int, expireAfterTime time.Duration, tryCount uint64, timerFunction func(srtId string, nbrId int, tryCount uint64)) bool {
 130         t.mutex.Lock()
 131         defer t.mutex.Unlock()
 132         if timerFunction == nil {
 133                 xapp.Logger.Error("StartTimer() timerFunc == nil\n")
 134                 return false
 135         }
 136         timerKey := TimerKey{strId, nbrId}
 137         // Stop timer if there is already timer running with the same id
 138         if val, ok := t.timer[timerKey]; ok {
 139                 xapp.Logger.Debug("StartTimer() old timer found")
 140                 if val.timerAddress != nil {
 141                         xapp.Logger.Debug("StartTimer() deleting old timer")
 142                         val.timerAddress.Stop()
 143                 }
 144                 delete(t.timer, timerKey)
 145         }
 146
 147         // Store in timerMap in-build Go "timer", timer function executor and the function to be executed when the timer expires
 148         t.timer[timerKey] = TimerInfo{timerAddress: time.AfterFunc(expireAfterTime, func() { t.timerFunctionExecutor(strId, nbrId) }),
 149                 timerFunctionAddress: func() { timerFunction(strId, nbrId, tryCount) }}
 150         return true
 151 }
 152
 153 func (t *TimerMap) StopTimer(strId string, nbrId int) bool {
 154         t.mutex.Lock()
 155         defer t.mutex.Unlock()
 156         timerKey := TimerKey{strId, nbrId}
 157         if val, ok := t.timer[timerKey]; ok {
 158                 if val.timerAddress != nil {
 159                         val.timerAddress.Stop()
 160                         delete(t.timer, timerKey)
 161                         return true
 162                 } else {
 163                         xapp.Logger.Error("StopTimer() timerAddress == nil")
 164                         return false
 165                 }
 166         } else {
 167                 xapp.Logger.Debug("StopTimer() Timer not found. May be expired or stopped already. timerKey.strId: %v, timerKey.strId: %v\n", timerKey.strId, timerKey.nbrId)
 168                 return false
 169         }
 170 }
 171
 172 func (t *TimerMap) timerFunctionExecutor(strId string, nbrId int) {
 173         t.mutex.Lock()
 174         timerKey := TimerKey{strId, nbrId}
 175         if val, ok := t.timer[timerKey]; ok {
 176                 if val.timerFunctionAddress != nil {
 177                         // Take local copy of timer function address
 178                         f := val.timerFunctionAddress
 179                         // Delete timer instance from map
 180                         delete(t.timer, timerKey)
 181                         t.mutex.Unlock()
 182                         // Execute the timer function
 183                         f()
 184                         return
 185                 } else {
 186                         xapp.Logger.Error("timerExecutorFunc() timerFunctionAddress == nil")
 187                         t.mutex.Unlock()
 188                         return
 189                 }
 190         } else {
 191                 xapp.Logger.Error("timerExecutorFunc() Timer is not anymore in map. timerKey.strId: %v, timerKey.strId: %v\n", timerKey.strId, timerKey.nbrId)
 192                 t.mutex.Unlock()
 193                 return
 194         }
 195 }