summaryrefslogtreecommitdiff
path: root/git-gui/lib/chord.tcl
diff options
context:
space:
mode:
Diffstat (limited to 'git-gui/lib/chord.tcl')
-rw-r--r--git-gui/lib/chord.tcl160
1 files changed, 160 insertions, 0 deletions
diff --git a/git-gui/lib/chord.tcl b/git-gui/lib/chord.tcl
new file mode 100644
index 0000000000..275a6cd4a1
--- /dev/null
+++ b/git-gui/lib/chord.tcl
@@ -0,0 +1,160 @@
+# Simple Chord for Tcl
+#
+# A "chord" is a method with more than one entrypoint and only one body, such
+# that the body runs only once all the entrypoints have been called by
+# different asynchronous tasks. In this implementation, the chord is defined
+# dynamically for each invocation. A SimpleChord object is created, supplying
+# body script to be run when the chord is completed, and then one or more notes
+# are added to the chord. Each note can be called like a proc, and returns
+# immediately if the chord isn't yet complete. When the last remaining note is
+# called, the body runs before the note returns.
+#
+# The SimpleChord class has a constructor that takes the body script, and a
+# method add_note that returns a note object. Since the body script does not
+# run in the context of the procedure that defined it, a mechanism is provided
+# for injecting variables into the chord for use by the body script. The
+# activation of a note is idempotent; multiple calls have the same effect as
+# a simple call.
+#
+# If you are invoking asynchronous operations with chord notes as completion
+# callbacks, and there is a possibility that earlier operations could complete
+# before later ones are started, it is a good practice to create a "common"
+# note on the chord that prevents it from being complete until you're certain
+# you've added all the notes you need.
+#
+# Example:
+#
+# # Turn off the UI while running a couple of async operations.
+# lock_ui
+#
+# set chord [SimpleChord new {
+# unlock_ui
+# # Note: $notice here is not referenced in the calling scope
+# if {$notice} { info_popup $notice }
+# }
+#
+# # Configure a note to keep the chord from completing until
+# # all operations have been initiated.
+# set common_note [$chord add_note]
+#
+# # Pass notes as 'after' callbacks to other operations
+# async_operation $args [$chord add_note]
+# other_async_operation $args [$chord add_note]
+#
+# # Communicate with the chord body
+# if {$condition} {
+# # This sets $notice in the same context that the chord body runs in.
+# $chord eval { set notice "Something interesting" }
+# }
+#
+# # Activate the common note, making the chord eligible to complete
+# $common_note
+#
+# At this point, the chord will complete at some unknown point in the future.
+# The common note might have been the first note activated, or the async
+# operations might have completed synchronously and the common note is the
+# last one, completing the chord before this code finishes, or anything in
+# between. The purpose of the chord is to not have to worry about the order.
+
+# SimpleChord class:
+# Represents a procedure that conceptually has multiple entrypoints that must
+# all be called before the procedure executes. Each entrypoint is called a
+# "note". The chord is only "completed" when all the notes are "activated".
+oo::class create SimpleChord {
+ variable notes body is_completed
+
+ # Constructor:
+ # set chord [SimpleChord new {body}]
+ # Creates a new chord object with the specified body script. The
+ # body script is evaluated at most once, when a note is activated
+ # and the chord has no other non-activated notes.
+ constructor {body} {
+ set notes [list]
+ my eval [list set body $body]
+ set is_completed 0
+ }
+
+ # Method:
+ # $chord eval {script}
+ # Runs the specified script in the same context (namespace) in which
+ # the chord body will be evaluated. This can be used to set variable
+ # values for the chord body to use.
+ method eval {script} {
+ namespace eval [self] $script
+ }
+
+ # Method:
+ # set note [$chord add_note]
+ # Adds a new note to the chord, an instance of ChordNote. Raises an
+ # error if the chord is already completed, otherwise the chord is
+ # updated so that the new note must also be activated before the
+ # body is evaluated.
+ method add_note {} {
+ if {$is_completed} { error "Cannot add a note to a completed chord" }
+
+ set note [ChordNote new [self]]
+
+ lappend notes $note
+
+ return $note
+ }
+
+ # This method is for internal use only and is intentionally undocumented.
+ method notify_note_activation {} {
+ if {!$is_completed} {
+ foreach note $notes {
+ if {![$note is_activated]} { return }
+ }
+
+ set is_completed 1
+
+ namespace eval [self] $body
+ namespace delete [self]
+ }
+ }
+}
+
+# ChordNote class:
+# Represents a note within a chord, providing a way to activate it. When the
+# final note of the chord is activated (this can be any note in the chord,
+# with all other notes already previously activated in any order), the chord's
+# body is evaluated.
+oo::class create ChordNote {
+ variable chord is_activated
+
+ # Constructor:
+ # Instances of ChordNote are created internally by calling add_note on
+ # SimpleChord objects.
+ constructor {chord} {
+ my eval set chord $chord
+ set is_activated 0
+ }
+
+ # Method:
+ # [$note is_activated]
+ # Returns true if this note has already been activated.
+ method is_activated {} {
+ return $is_activated
+ }
+
+ # Method:
+ # $note
+ # Activates the note, if it has not already been activated, and
+ # completes the chord if there are no other notes awaiting
+ # activation. Subsequent calls will have no further effect.
+ #
+ # NB: In TclOO, if an object is invoked like a method without supplying
+ # any method name, then this internal method `unknown` is what
+ # actually runs (with no parameters). It is used in the ChordNote
+ # class for the purpose of allowing the note object to be called as
+ # a function (see example above). (The `unknown` method can also be
+ # used to support dynamic dispatch, but must take parameters to
+ # identify the "unknown" method to be invoked. In this form, this
+ # proc serves only to make instances behave directly like methods.)
+ method unknown {} {
+ if {!$is_activated} {
+ set is_activated 1
+ $chord notify_note_activation
+ }
+ }
+}