logdog: Add bundler library.

client/internal/logdog/butler/bundler/bundler.go

+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package bundler
+
+import (
+        "github.com/luci/luci-go/common/logdog/protocol"
+)
+
+// Config contains configuration information for a Bundler instance.
+type Config struct {
+        // Sizer is the Sizer instance to use to help with Bundler accounting.

[tandrii(chromium), 2015/08/11 14:06:07]

start comment with func name "// NewSizer

[dnj (Google), 2015/08/11 16:24:00]

Done.

+        // If nil, a FastSizer will be used.
+        NewSizer func(*protocol.ButlerLogBundle) Sizer
+}
+
+// Sizer is a stateful instance that tracks the size of LogDog ButlerLogBundle
+// protobufs as they are constructed.
+//
+// A Sizer may overestimate the size, but it should strive to never
+// underestimate the size.
+type Sizer interface {
+        // Size returns the current size.
+        Size() int

[tandrii(chromium), 2015/08/11 14:06:07]

is int enough? maybe int64?

[dnj (Google), 2015/08/11 16:24:00]

Int should be enough, since in practice the size constraint is going to be in
the 1-10MB range, but I'll bump to int64 for purity's sake.

+
+        // AppendBundleEntry adds a ButlerLogBundle_Entry to the Sizer and returns
+        // its calculated size.
+        AppendBundleEntry(*protocol.ButlerLogBundle_Entry)

[tandrii(chromium), 2015/08/11 14:06:07]

this doesn't return

[dnj (Google), 2015/08/11 16:24:01]

It sure doesn't. Done.

+
+        // AppendLogEntry adds a LogEntry to the Sizer and returns its calculated
+        // size.
+        AppendLogEntry(*protocol.ButlerLogBundle_Entry, *protocol.LogEntry)

[tandrii(chromium), 2015/08/11 14:06:07]

this doesn't return

[dnj (Google), 2015/08/11 16:24:01]

Acknowledged.

+}
+
+// Bundler aggregates multiple Butler log bundle entries together into a single
+// log bundle. A Bundler is not goroutine-safe.
+//
+// A Bundler can vet incoming data, rejecting it if its serialized protobuf
+// exceeds a size threshold. For efficiency, the Bundler performs a conservative
+// estimate of the sizes.
+type Bundler interface {
+        // Append adds a single stream's bundle entry to the Bundler.
+        Append(*protocol.ButlerLogBundle_Entry)
+
+        // Bundle converts the current set of buffered log data into a series of

[tandrii(chromium), 2015/08/11 14:06:07]

nit: s/Bundle/GetBundles

[dnj (Google), 2015/08/11 16:24:00]

Done.

+        // ButlerLogBundle instances. Afterwards, the Bundler will no longer contain
+        // any buffered data.
+        //
+        // If the supplied threshold value is greater than zero, the returned bundle
+        // will only contain enough log messages such that its serialized protobuf
+        // byte count is less or equal to the threshold.
+        //
+        // Bundle may return nil if the Bundler has no accumulated data.
+        GetBundles(int) []*protocol.ButlerLogBundle
+
+        // Size returns the Bundler's current size.
+        Size() int
+
+        // Empty returns true if the Bundler has no buffered log data.
+        Empty() bool
+}