logdog: Add frame read/write library.

common/logdog/frame/writer.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 frame
+
+import (
+        "bytes"
+        "encoding/binary"
+        "io"
+)
+
+type frameWriter interface {
+        io.WriteCloser
+
+        // Flush creates a new frame for the buffered written data.
+        Flush() error
+}

[iannucci, 2015/08/03 22:21:24]

interface assertion

[dnj, 2015/08/03 22:42:58]

(see above, NewWriter).

+
+// WriteFrame writes a single frame to an io.Writer.
+func WriteFrame(w io.Writer, frame []byte) (int, error) {
+        var sizeBuf [binary.MaxVarintLen64]byte

[iannucci, 2015/08/03 22:21:24]

why not just `make([]byte, binary.MaxVarintLen64)`?

[dnj, 2015/08/03 22:42:58]

I _think_ because this is a stack allocation, and I'd prefer that to a heap
allocation since the number is known/small.

[iannucci, 2015/08/04 17:13:50]

No it's not... the compiler analyzes all pointers to determine if they escape in
order to put them on the stack or the heap. You can pass a pointer to sizeBuf
out of this function without issue. This isn't C++ :)

Also... you realize that stack frames in go are allocated on the heap, right?

https://golang.org/doc/faq#stack_or_heap

https://groups.google.com/forum/#!topic/golang-nuts/KdbtOqNK6JQ

[dnj, 2015/08/04 17:51:41]

Oh, interesting. I didn't know that. This suggests that the slice itself can
also be allocated on the stack.

It looks like you aren't supposed to care. "make" probably collapses into the
same things (array allocation + several slice allocations). It _should_ be easy
enough for Go compiler to choose stack here in either case.

I'll go ahead and use "make" because it is more conventional, but I don't think
there's anything inherently wrong with this notation even if the attempt to
optimize is taken out of the picture.
Sure, but even so stack growth is more efficient than individual heap
allocations.

+        sizeBytes := binary.PutUvarint(sizeBuf[:], uint64(len(frame)))
+
+        count, err := w.Write(sizeBuf[:sizeBytes])
+        if err != nil {
+                return count, err
+        }
+
+        amount, err := w.Write(frame)
+        count += amount
+        if err != nil {
+                return count, err
+        }
+
+        return count, nil
+}
+
+// Writer implements the io.Writer interface. Data written to the Writer is
+// translated into a series of frames. Each frame is spearated by a call to
+// Flush.
+//
+// Frame boundaries are created by calling Flush or Close. Close does not close
+// the wrapped Writer.
+//
+// Flush will always write a frame, even if the frame's data size is zero.
+// Close, on the other hand, will only write a frame if at least one Write
+// (even for zero bytes) has been called for that frame.

[iannucci, 2015/08/03 22:21:24]

I don't think this is true anymore? Looks like this is just Writer+Flush, not
WriterCloser+Flush

[dnj, 2015/08/03 22:42:58]

Oh sorry, updated.

+//
+// Data written over consecutive Write calls belongs to the same frame. It is
+// buffered until a frame boundary is created.
+type Writer interface {
+        io.Writer
+
+        // Flush writes the buffered frame
+        Flush() error
+}
+
+// writer implements the Writer interface by wrapping an io.Writer.
+type writer struct {
+        inner io.Writer
+        buf   bytes.Buffer
+}
+
+// NewWriter creates a new Writer instance that data as frames to an underlying
+// io.Writer.
+func NewWriter(w io.Writer) Writer {
+        return &writer{
+                inner: w,
+        }
+}
+
+func (w *writer) Write(data []byte) (int, error) {
+        return w.buf.Write(data)
+}
+
+func (w *writer) Flush() error {
+        _, err := WriteFrame(w.inner, w.buf.Bytes())
+        if err != nil {
+                return err
+        }
+
+        w.buf.Reset()
+        return nil
+}