| 1 | # Simple Chord for Tcl |
| 2 | # |
| 3 | # A "chord" is a method with more than one entrypoint and only one body, such |
| 4 | # that the body runs only once all the entrypoints have been called by |
| 5 | # different asynchronous tasks. In this implementation, the chord is defined |
| 6 | # dynamically for each invocation. A SimpleChord object is created, supplying |
| 7 | # body script to be run when the chord is completed, and then one or more notes |
| 8 | # are added to the chord. Each note can be called like a proc, and returns |
| 9 | # immediately if the chord isn't yet complete. When the last remaining note is |
| 10 | # called, the body runs before the note returns. |
| 11 | # |
| 12 | # The SimpleChord class has a constructor that takes the body script, and a |
| 13 | # method add_note that returns a note object. Since the body script does not |
| 14 | # run in the context of the procedure that defined it, a mechanism is provided |
| 15 | # for injecting variables into the chord for use by the body script. The |
| 16 | # activation of a note is idempotent; multiple calls have the same effect as |
| 17 | # a simple call. |
| 18 | # |
| 19 | # If you are invoking asynchronous operations with chord notes as completion |
| 20 | # callbacks, and there is a possibility that earlier operations could complete |
| 21 | # before later ones are started, it is a good practice to create a "common" |
| 22 | # note on the chord that prevents it from being complete until you're certain |
| 23 | # you've added all the notes you need. |
| 24 | # |
| 25 | # Example: |
| 26 | # |
| 27 | # # Turn off the UI while running a couple of async operations. |
| 28 | # lock_ui |
| 29 | # |
| 30 | # set chord [SimpleChord::new { |
| 31 | # unlock_ui |
| 32 | # # Note: $notice here is not referenced in the calling scope |
| 33 | # if {$notice} { info_popup $notice } |
| 34 | # } |
| 35 | # |
| 36 | # # Configure a note to keep the chord from completing until |
| 37 | # # all operations have been initiated. |
| 38 | # set common_note [$chord add_note] |
| 39 | # |
| 40 | # # Activate notes in 'after' callbacks to other operations |
| 41 | # set newnote [$chord add_note] |
| 42 | # async_operation $args [list $newnote activate] |
| 43 | # |
| 44 | # # Communicate with the chord body |
| 45 | # if {$condition} { |
| 46 | # # This sets $notice in the same context that the chord body runs in. |
| 47 | # $chord eval { set notice "Something interesting" } |
| 48 | # } |
| 49 | # |
| 50 | # # Activate the common note, making the chord eligible to complete |
| 51 | # $common_note activate |
| 52 | # |
| 53 | # At this point, the chord will complete at some unknown point in the future. |
| 54 | # The common note might have been the first note activated, or the async |
| 55 | # operations might have completed synchronously and the common note is the |
| 56 | # last one, completing the chord before this code finishes, or anything in |
| 57 | # between. The purpose of the chord is to not have to worry about the order. |
| 58 | |
| 59 | # SimpleChord class: |
| 60 | # Represents a procedure that conceptually has multiple entrypoints that must |
| 61 | # all be called before the procedure executes. Each entrypoint is called a |
| 62 | # "note". The chord is only "completed" when all the notes are "activated". |
| 63 | class SimpleChord { |
| 64 | field notes |
| 65 | field body |
| 66 | field is_completed |
| 67 | field eval_ns |
| 68 | |
| 69 | # Constructor: |
| 70 | # set chord [SimpleChord::new {body}] |
| 71 | # Creates a new chord object with the specified body script. The |
| 72 | # body script is evaluated at most once, when a note is activated |
| 73 | # and the chord has no other non-activated notes. |
| 74 | constructor new {i_body} { |
| 75 | set notes [list] |
| 76 | set body $i_body |
| 77 | set is_completed 0 |
| 78 | set eval_ns "[namespace qualifiers $this]::eval" |
| 79 | return $this |
| 80 | } |
| 81 | |
| 82 | # Method: |
| 83 | # $chord eval {script} |
| 84 | # Runs the specified script in the same context (namespace) in which |
| 85 | # the chord body will be evaluated. This can be used to set variable |
| 86 | # values for the chord body to use. |
| 87 | method eval {script} { |
| 88 | namespace eval $eval_ns $script |
| 89 | } |
| 90 | |
| 91 | # Method: |
| 92 | # set note [$chord add_note] |
| 93 | # Adds a new note to the chord, an instance of ChordNote. Raises an |
| 94 | # error if the chord is already completed, otherwise the chord is |
| 95 | # updated so that the new note must also be activated before the |
| 96 | # body is evaluated. |
| 97 | method add_note {} { |
| 98 | if {$is_completed} { error "Cannot add a note to a completed chord" } |
| 99 | |
| 100 | set note [ChordNote::new $this] |
| 101 | |
| 102 | lappend notes $note |
| 103 | |
| 104 | return $note |
| 105 | } |
| 106 | |
| 107 | # This method is for internal use only and is intentionally undocumented. |
| 108 | method notify_note_activation {} { |
| 109 | if {!$is_completed} { |
| 110 | foreach note $notes { |
| 111 | if {![$note is_activated]} { return } |
| 112 | } |
| 113 | |
| 114 | set is_completed 1 |
| 115 | |
| 116 | namespace eval $eval_ns $body |
| 117 | delete_this |
| 118 | } |
| 119 | } |
| 120 | } |
| 121 | |
| 122 | # ChordNote class: |
| 123 | # Represents a note within a chord, providing a way to activate it. When the |
| 124 | # final note of the chord is activated (this can be any note in the chord, |
| 125 | # with all other notes already previously activated in any order), the chord's |
| 126 | # body is evaluated. |
| 127 | class ChordNote { |
| 128 | field chord |
| 129 | field is_activated |
| 130 | |
| 131 | # Constructor: |
| 132 | # Instances of ChordNote are created internally by calling add_note on |
| 133 | # SimpleChord objects. |
| 134 | constructor new {c} { |
| 135 | set chord $c |
| 136 | set is_activated 0 |
| 137 | return $this |
| 138 | } |
| 139 | |
| 140 | # Method: |
| 141 | # [$note is_activated] |
| 142 | # Returns true if this note has already been activated. |
| 143 | method is_activated {} { |
| 144 | return $is_activated |
| 145 | } |
| 146 | |
| 147 | # Method: |
| 148 | # $note activate |
| 149 | # Activates the note, if it has not already been activated, and |
| 150 | # completes the chord if there are no other notes awaiting |
| 151 | # activation. Subsequent calls will have no further effect. |
| 152 | method activate {} { |
| 153 | if {!$is_activated} { |
| 154 | set is_activated 1 |
| 155 | $chord notify_note_activation |
| 156 | } |
| 157 | } |
| 158 | } |