docs for mfs system method impls
License: MIT Signed-off-by: ForrestWeston <forrest@protocol.ai>
ForrestWeston committed
Jan 22, 2018 at 14:51 UTC
d3f5ee22401c796eb4a9e1311337002b97693635
1 file changed
+17
-10
mfs/system.go
+17
-10
@@ -41,19 +41,19 @@ const (
41
TDir
42
)
43
44
-// FSNode represents any node (directory, root, or file) in the mfs filesystem
44
+// FSNode represents any node (directory, root, or file) in the mfs filesystem.
45
type FSNode interface {
46
GetNode() (node.Node, error)
47
Flush() error
48
Type() NodeType
49
}
50
51
-// Root represents the root of a filesystem tree
51
+// Root represents the root of a filesystem tree.
52
type Root struct {
53
- // node is the merkledag root
53
+ // node is the merkledag root.
54
node *dag.ProtoNode
55
56
- // val represents the node. It can either be a File or a Directory
56
+ // val represents the node. It can either be a File or a Directory.
57
val FSNode
58
59
repub *Republisher
@@ -63,9 +63,10 @@ type Root struct {
63
Type string
64
}
65
66
+// PubFunc is the function used by the `publish()` method.
67
type PubFunc func(context.Context, *cid.Cid) error
68
68
-// newRoot creates a new Root and starts up a republisher routine for it
69
+// NewRoot creates a new Root and starts up a republisher routine for it.
70
func NewRoot(parent context.Context, ds dag.DAGService, node *dag.ProtoNode, pf PubFunc) (*Root, error) {
71
72
var repub *Republisher
@@ -107,10 +108,13 @@ func NewRoot(parent context.Context, ds dag.DAGService, node *dag.ProtoNode, pf
108
return root, nil
109
}
110
111
+// GetValue returns the value of Root.
112
func (kr *Root) GetValue() FSNode {
113
return kr.val
114
}
115
116
+// Flush signals that an update has occurred since the last publish,
117
+// and updates the Root republisher.
118
func (kr *Root) Flush() error {
119
nd, err := kr.GetValue().GetNode()
120
if err != nil {
@@ -154,7 +158,7 @@ func (kr *Root) FlushMemFree(ctx context.Context) error {
158
}
159
160
// closeChild implements the childCloser interface, and signals to the publisher that
157
-// there are changes ready to be published
161
+// there are changes ready to be published.
162
func (kr *Root) closeChild(name string, nd node.Node, sync bool) error {
163
c, err := kr.dserv.Add(nd)
164
if err != nil {
@@ -181,7 +185,7 @@ func (kr *Root) Close() error {
185
return nil
186
}
187
184
-// Republisher manages when to publish a given entry
188
+// Republisher manages when to publish a given entry.
189
type Republisher struct {
190
TimeoutLong time.Duration
191
TimeoutShort time.Duration
@@ -198,7 +202,7 @@ type Republisher struct {
202
}
203
204
// NewRepublisher creates a new Republisher object to republish the given root
201
-// using the given short and long time intervals
205
+// using the given short and long time intervals.
206
func NewRepublisher(ctx context.Context, pf PubFunc, tshort, tlong time.Duration) *Republisher {
207
ctx, cancel := context.WithCancel(ctx)
208
return &Republisher{
@@ -218,6 +222,8 @@ func (p *Republisher) setVal(c *cid.Cid) {
222
p.val = c
223
}
224
225
+// WaitPub Returns immediately if `lastpub` value is consistent with the
226
+// current value `val`, else will block until `val` has been published.
227
func (p *Republisher) WaitPub() {
228
p.lk.Lock()
229
consistent := p.lastpub == p.val
@@ -239,7 +245,7 @@ func (p *Republisher) Close() error {
245
246
// Touch signals that an update has occurred since the last publish.
247
// Multiple consecutive touches may extend the time period before
242
-// the next Publish occurs in order to more efficiently batch updates
248
+// the next Publish occurs in order to more efficiently batch updates.
249
func (np *Republisher) Update(c *cid.Cid) {
250
np.setVal(c)
251
select {
@@ -248,7 +254,7 @@ func (np *Republisher) Update(c *cid.Cid) {
254
}
255
}
256
251
-// Run is the main republisher loop
257
+// Run is the main republisher loop.
258
func (np *Republisher) Run() {
259
for {
260
select {
@@ -284,6 +290,7 @@ func (np *Republisher) Run() {
290
}
291
}
292
293
+// publish calls the `PubFunc`.
294
func (np *Republisher) publish(ctx context.Context) error {
295
np.lk.Lock()
296
topub := np.val