From 1460ee6b4b5b43d696b95d44ca6853b2edb65805 Mon Sep 17 00:00:00 2001
From: diamondburned <datutbrus@gmail.com>
Date: Wed, 13 Jan 2021 16:17:55 -0800
Subject: [PATCH] Allow IOMethods to be explicit disposers

This commit changes IOMethods and clarifies stop functions that they
will act as destructors or disposers for whatever interface that
implements the methods, and that both the backend and frontend should
free that interface when they're called.

This commit is added as part of the IPC protocol.
---
 cchat.go                                      |   6 +++---
 .../cchat-generator/generate_interface.go     |   6 +++++-
 repository/gob/repository.gob                 | Bin 38253 -> 38269 bytes
 repository/interface.go                       |  17 +++++++++++++++++
 repository/main.go                            |   5 +++--
 5 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/cchat.go b/cchat.go
index b0aaa04..366efdd 100644
--- a/cchat.go
+++ b/cchat.go
@@ -237,7 +237,7 @@ type Author interface {
 
 // Backlogger adds message history capabilities into a message container. The
 // backend should send old messages using the MessageCreate method of the
-// MessageContainer, and the frontend should automatically sort messages based
+// MessagesContainer, and the frontend should automatically sort messages based
 // on the timestamp.
 //
 // As there is no stop callback, if the backend needs to fetch messages
@@ -755,7 +755,7 @@ type Service interface {
 //
 // A session can implement SessionSaver, which would allow the frontend to save
 // the session into its keyring at any time. Whether the keyring is completely
-// secure or not is up to the frontend. For a Gtk client, that would be using
+// secure or not is up to the frontend. For a GTK client, that would be using
 // the GNOME Keyring daemon.
 type Session interface {
 	// Identifier should typically return the user ID.
@@ -776,7 +776,7 @@ type Session interface {
 	// When this function fails, the frontend may display the error upfront.
 	// However, it will treat the session as actually disconnected. If needed, the
 	// backend must implement reconnection by itself.
-	Disconnect() error // Blocking
+	Disconnect() error // Blocking, Disposer
 
 	// Asserters.
 
diff --git a/cmd/internal/cchat-generator/generate_interface.go b/cmd/internal/cchat-generator/generate_interface.go
index 8e1d9f9..da4efc7 100644
--- a/cmd/internal/cchat-generator/generate_interface.go
+++ b/cmd/internal/cchat-generator/generate_interface.go
@@ -69,7 +69,11 @@ func generateInterfaces(ifaces []repository.Interface) jen.Code {
 				case repository.IOMethod:
 					stmt.Params(generateFuncParams(method.Parameters, "")...)
 					stmt.Params(generateFuncParamErr(method.ReturnValue, method.ErrorType)...)
-					stmt.Comment("// Blocking")
+					var comment = "Blocking"
+					if method.Disposer {
+						comment += ", Disposer"
+					}
+					stmt.Comment("// " + comment)
 				case repository.ContainerMethod:
 					stmt.Params(generateContainerFuncParams(method)...)
 					stmt.Params(generateContainerFuncReturns(method)...)
diff --git a/repository/gob/repository.gob b/repository/gob/repository.gob
index a404ff4fb9294e5a2fce518e754d933fe8c5c851..6b9e5c960af25dded3428e683fe5eb5232de1f5e 100644
GIT binary patch
delta 94
zcmV-k0HOcwssjD00<fk$0uBnZs65LJ0R)qDN-q)t2t;XfaBp*EasdJW0090aWwWSC
zJOu(&OS9%rH~|a{0ssL8WpZ+FasdI8!3;c;?p_A7YEk_W0q2uwW2OOfvkqimG2r?i
A*Z=?k

delta 66
zcmV-I0KNbHssin*0<fk$0uBAMs65LJ0RxkCN-qTf0RAOnv$aY*1p;(yv-3|l0h2Ck
Y3zO+pL9=;L{Sg7?lXqjLvmRt$F^&To^8f$<

diff --git a/repository/interface.go b/repository/interface.go
index d70a12c..e67b102 100644
--- a/repository/interface.go
+++ b/repository/interface.go
@@ -69,6 +69,9 @@ func (m GetterMethod) ReturnError() bool {
 // SetterMethod is a method that sets values. These methods must not do IO, and
 // they have to be non-blocking. They're used only for containers. Actual setter
 // methods implemented by the backend belongs to IOMethods.
+//
+// Clients should always keep track of the values given to setters and free them
+// once the setters are called again with new values.
 type SetterMethod struct {
 	method
 
@@ -90,6 +93,17 @@ type IOMethod struct {
 	// returns. For the most part, this field should be "error" if that is the
 	// case, but some methods may choose to extend the error base type.
 	ErrorType string
+	// Disposer indicates that this method signals the disposal of the interface
+	// that implements it. This is used similarly to stop functions, except all
+	// disposer functions can be synchronous, and the frontend should handle
+	// indicating such. The frontend can also ignore the result and run the
+	// method in a dangling goroutine, but it must gracefully wait for it to be
+	// done on exit.
+	//
+	// Similarly to the stop function, the instance that the disposer method belongs
+	// to will also be considered invalid and should be freed once the function
+	// returns regardless of the error.
+	Disposer bool
 }
 
 // ReturnError returns true if the method can error out.
@@ -110,6 +124,9 @@ type ContainerMethod struct {
 	// HasStopFn is true if the function returns a callback of type func() as
 	// its first return. The function will return an error in addition. If this
 	// is false, then only the error is returned.
+	//
+	// Once the stop function is called, the instance that the method belongs to
+	// will also be considered invalidated and should be freed accordingly.
 	HasStopFn bool
 }
 
diff --git a/repository/main.go b/repository/main.go
index 7eb1bb5..6c07404 100644
--- a/repository/main.go
+++ b/repository/main.go
@@ -848,7 +848,7 @@ var Main = Packages{
 				A session can implement SessionSaver, which would allow the
 				frontend to save the session into its keyring at any time.
 				Whether the keyring is completely secure or not is up to the
-				frontend. For a Gtk client, that would be using the GNOME
+				frontend. For a GTK client, that would be using the GNOME
 				Keyring daemon.
 			`},
 			Name: "Session",
@@ -888,6 +888,7 @@ var Main = Packages{
 						Name: "Disconnect",
 					},
 					ErrorType: "error",
+					Disposer:  true,
 				},
 				AsserterMethod{ChildType: "Commander"},
 				AsserterMethod{ChildType: "SessionSaver"},
@@ -1202,7 +1203,7 @@ var Main = Packages{
 			Comment: Comment{`
 				Backlogger adds message history capabilities into a message
 				container. The backend should send old messages using the
-				MessageCreate method of the MessageContainer, and the frontend
+				MessageCreate method of the MessagesContainer, and the frontend
 				should automatically sort messages based on the timestamp.
 
 				As there is no stop callback, if the backend needs to fetch