types.go 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226
  1. /*
  2. * ECAL
  3. *
  4. * Copyright 2020 Matthias Ladkau. All rights reserved.
  5. *
  6. * This Source Code Form is subject to the terms of the MIT
  7. * License, If a copy of the MIT License was not distributed with this
  8. * file, You can obtain one at https://opensource.org/licenses/MIT.
  9. */
  10. package util
  11. import (
  12. "time"
  13. "devt.de/krotik/common/datautil"
  14. "devt.de/krotik/ecal/parser"
  15. )
  16. /*
  17. Processor models a top level execution instance for ECAL.
  18. */
  19. type Processor interface {
  20. }
  21. /*
  22. ECALImportLocator is used to resolve imports.
  23. */
  24. type ECALImportLocator interface {
  25. /*
  26. Resolve a given import path and parse the imported file into an AST.
  27. */
  28. Resolve(path string) (string, error)
  29. }
  30. /*
  31. ECALFunction models a callable function in ECAL.
  32. */
  33. type ECALFunction interface {
  34. /*
  35. Run executes this function. The envirnment provides a unique instanceID for
  36. every code location in the running code, the variable scope of the function,
  37. an instance state which can be used in combinartion with the instanceID
  38. to store instance specific state (e.g. for iterator functions) and a list
  39. of argument values which were passed to the function by the calling code.
  40. */
  41. Run(instanceID string, vs parser.Scope, is map[string]interface{}, tid uint64, args []interface{}) (interface{}, error)
  42. /*
  43. DocString returns a descriptive text about this function.
  44. */
  45. DocString() (string, error)
  46. }
  47. /*
  48. ECALPluginFunction models a callable function in ECAL which can be imported via a plugin.
  49. */
  50. type ECALPluginFunction interface {
  51. /*
  52. Run executes this function with a given list of arguments.
  53. */
  54. Run(args []interface{}) (interface{}, error)
  55. /*
  56. DocString returns a descriptive text about this function.
  57. */
  58. DocString() string
  59. }
  60. /*
  61. Logger is required external object to which the interpreter releases its log messages.
  62. */
  63. type Logger interface {
  64. /*
  65. LogError adds a new error log message.
  66. */
  67. LogError(v ...interface{})
  68. /*
  69. LogInfo adds a new info log message.
  70. */
  71. LogInfo(v ...interface{})
  72. /*
  73. LogDebug adds a new debug log message.
  74. */
  75. LogDebug(v ...interface{})
  76. }
  77. /*
  78. ContType represents a way how to resume code execution of a suspended thread.
  79. */
  80. type ContType int
  81. /*
  82. Available lexer token types
  83. */
  84. const (
  85. Resume ContType = iota // Resume code execution until the next breakpoint or the end
  86. StepIn // Step into a function call or over the next non-function call
  87. StepOver // Step over the current statement onto the next line
  88. StepOut // Step out of the current function call
  89. )
  90. /*
  91. ECALDebugger is a debugging object which can be used to inspect and modify a running
  92. ECAL environment.
  93. */
  94. type ECALDebugger interface {
  95. /*
  96. HandleInput handles a given debug instruction. It must be possible to
  97. convert the output data into a JSON string.
  98. */
  99. HandleInput(input string) (interface{}, error)
  100. /*
  101. StopThreads will continue all suspended threads and set them to be killed.
  102. Returns true if a waiting thread was resumed. Can wait for threads to end
  103. by ensuring that for at least d time no state change occurred.
  104. */
  105. StopThreads(d time.Duration) bool
  106. /*
  107. BreakOnStart breaks on the start of the next execution.
  108. */
  109. BreakOnStart(flag bool)
  110. /*
  111. BreakOnError breaks if an error occurs.
  112. */
  113. BreakOnError(flag bool)
  114. /*
  115. SetLockingState sets locking status information.
  116. */
  117. SetLockingState(mutexeOwners map[string]uint64, mutexLog *datautil.RingBuffer)
  118. /*
  119. VisitState is called for every state during the execution of a program.
  120. */
  121. VisitState(node *parser.ASTNode, vs parser.Scope, tid uint64) TraceableRuntimeError
  122. /*
  123. VisitStepInState is called before entering a function call.
  124. */
  125. VisitStepInState(node *parser.ASTNode, vs parser.Scope, tid uint64) TraceableRuntimeError
  126. /*
  127. VisitStepOutState is called after returning from a function call.
  128. */
  129. VisitStepOutState(node *parser.ASTNode, vs parser.Scope, tid uint64, soErr error) TraceableRuntimeError
  130. /*
  131. RecordThreadFinished lets the debugger know that a thread has finished.
  132. */
  133. RecordThreadFinished(tid uint64)
  134. /*
  135. SetBreakPoint sets a break point.
  136. */
  137. SetBreakPoint(source string, line int)
  138. /*
  139. DisableBreakPoint disables a break point but keeps the code reference.
  140. */
  141. DisableBreakPoint(source string, line int)
  142. /*
  143. RemoveBreakPoint removes a break point.
  144. */
  145. RemoveBreakPoint(source string, line int)
  146. /*
  147. ExtractValue copies a value from a suspended thread into the
  148. global variable scope.
  149. */
  150. ExtractValue(threadID uint64, varName string, destVarName string) error
  151. /*
  152. InjectValue copies a value from an expression (using the global
  153. variable scope) into a suspended thread.
  154. */
  155. InjectValue(threadID uint64, varName string, expression string) error
  156. /*
  157. Continue will continue a suspended thread.
  158. */
  159. Continue(threadID uint64, contType ContType)
  160. /*
  161. Status returns the current status of the debugger.
  162. */
  163. Status() interface{}
  164. /*
  165. LockStatus returns the current locking status.
  166. */
  167. LockState() interface{}
  168. /*
  169. Describe describes a thread currently observed by the debugger.
  170. */
  171. Describe(threadID uint64) interface{}
  172. }
  173. /*
  174. DebugCommand is command which can modify and interrogate the debugger.
  175. */
  176. type DebugCommand interface {
  177. /*
  178. Execute the debug command and return its result. It must be possible to
  179. convert the output data into a JSON string.
  180. */
  181. Run(debugger ECALDebugger, args []string) (interface{}, error)
  182. /*
  183. DocString returns a descriptive text about this command.
  184. */
  185. DocString() string
  186. }