document how to get best performance

example_test.go

@@ -45,3 +45,47 @@ func ExampleUnmarshal() {
 	// Output:
 	// [{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]
 }
+
+
+func ExampleMarshalWithBestPerformance() {
+	type ColorGroup struct {
+		ID     int
+		Name   string
+		Colors []string
+	}
+	group := ColorGroup{
+		ID:     1,
+		Name:   "Reds",
+		Colors: []string{"Crimson", "Red", "Ruby", "Maroon"},
+	}
+	stream := jsoniter.ConfigFastest.BorrowStream(nil)
+	defer jsoniter.ConfigFastest.ReturnStream(stream)
+	stream.WriteVal(group)
+	if stream.Error != nil {
+		fmt.Println("error:", stream.Error)
+	}
+	os.Stdout.Write(stream.Buffer())
+	// Output:
+	// {"ID":1,"Name":"Reds","Colors":["Crimson","Red","Ruby","Maroon"]}
+}
+
+func ExampleUnmarshalWithBestPerformance() {
+	var jsonBlob = []byte(`[
+		{"Name": "Platypus", "Order": "Monotremata"},
+		{"Name": "Quoll",    "Order": "Dasyuromorphia"}
+	]`)
+	type Animal struct {
+		Name  string
+		Order string
+	}
+	var animals []Animal
+	iter := jsoniter.ConfigFastest.BorrowIterator(jsonBlob)
+	defer jsoniter.ConfigFastest.ReturnIterator(iter)
+	iter.ReadVal(&animals)
+	if iter.Error != nil {
+		fmt.Println("error:", iter.Error)
+	}
+	fmt.Printf("%+v", animals)
+	// Output:
+	// [{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]
+}

feature_config.go

@@ -149,8 +149,8 @@ func (cfg *frozenConfig) CleanEncoders() {
 }
 
 func (cfg *frozenConfig) MarshalToString(v interface{}) (string, error) {
-	stream := cfg.borrowStream()
-	defer cfg.returnStream(stream)
+	stream := cfg.BorrowStream(nil)
+	defer cfg.ReturnStream(stream)
 	stream.WriteVal(v)
 	if stream.Error != nil {
 		return "", stream.Error
@@ -159,8 +159,8 @@ func (cfg *frozenConfig) MarshalToString(v interface{}) (string, error) {
 }
 
 func (cfg *frozenConfig) Marshal(v interface{}) ([]byte, error) {
-	stream := cfg.borrowStream()
-	defer cfg.returnStream(stream)
+	stream := cfg.BorrowStream(nil)
+	defer cfg.ReturnStream(stream)
 	stream.WriteVal(v)
 	if stream.Error != nil {
 		return nil, stream.Error
@@ -174,8 +174,8 @@ func (cfg *frozenConfig) Marshal(v interface{}) ([]byte, error) {
 func (cfg *frozenConfig) UnmarshalFromString(str string, v interface{}) error {
 	data := []byte(str)
 	data = data[:lastNotSpacePos(data)]
-	iter := cfg.borrowIterator(data)
-	defer cfg.returnIterator(iter)
+	iter := cfg.BorrowIterator(data)
+	defer cfg.ReturnIterator(iter)
 	iter.ReadVal(v)
 	if iter.head == iter.tail {
 		iter.loadMore()
@@ -192,8 +192,8 @@ func (cfg *frozenConfig) UnmarshalFromString(str string, v interface{}) error {
 func (cfg *frozenConfig) UnmarshalAnyFromString(str string) (Any, error) {
 	data := []byte(str)
 	data = data[:lastNotSpacePos(data)]
-	iter := cfg.borrowIterator(data)
-	defer cfg.returnIterator(iter)
+	iter := cfg.BorrowIterator(data)
+	defer cfg.ReturnIterator(iter)
 	any := iter.ReadAny()
 	if iter.head == iter.tail {
 		iter.loadMore()
@@ -209,8 +209,8 @@ func (cfg *frozenConfig) UnmarshalAnyFromString(str string) (Any, error) {
 
 func (cfg *frozenConfig) UnmarshalAny(data []byte) (Any, error) {
 	data = data[:lastNotSpacePos(data)]
-	iter := cfg.borrowIterator(data)
-	defer cfg.returnIterator(iter)
+	iter := cfg.BorrowIterator(data)
+	defer cfg.ReturnIterator(iter)
 	any := iter.ReadAny()
 	if iter.head == iter.tail {
 		iter.loadMore()
@@ -226,8 +226,8 @@ func (cfg *frozenConfig) UnmarshalAny(data []byte) (Any, error) {
 
 func (cfg *frozenConfig) Unmarshal(data []byte, v interface{}) error {
 	data = data[:lastNotSpacePos(data)]
-	iter := cfg.borrowIterator(data)
-	defer cfg.returnIterator(iter)
+	iter := cfg.BorrowIterator(data)
+	defer cfg.ReturnIterator(iter)
 	typ := reflect.TypeOf(v)
 	if typ.Kind() != reflect.Ptr {
 		// return non-pointer error

feature_pool.go

@@ -1,16 +1,18 @@
 package jsoniter
 
-func (cfg *frozenConfig) borrowStream() *Stream {
+import "io"
+
+func (cfg *frozenConfig) BorrowStream(writer io.Writer) *Stream {
 	select {
 	case stream := <-cfg.streamPool:
-		stream.Reset(nil)
+		stream.Reset(writer)
 		return stream
 	default:
-		return NewStream(cfg, nil, 512)
+		return NewStream(cfg, writer, 512)
 	}
 }
 
-func (cfg *frozenConfig) returnStream(stream *Stream) {
+func (cfg *frozenConfig) ReturnStream(stream *Stream) {
 	select {
 	case cfg.streamPool <- stream:
 		return
@@ -19,7 +21,7 @@ func (cfg *frozenConfig) returnStream(stream *Stream) {
 	}
 }
 
-func (cfg *frozenConfig) borrowIterator(data []byte) *Iterator {
+func (cfg *frozenConfig) BorrowIterator(data []byte) *Iterator {
 	select {
 	case iter := <- cfg.iteratorPool:
 		iter.ResetBytes(data)
@@ -29,7 +31,7 @@ func (cfg *frozenConfig) borrowIterator(data []byte) *Iterator {
 	}
 }
 
-func (cfg *frozenConfig) returnIterator(iter *Iterator) {
+func (cfg *frozenConfig) ReturnIterator(iter *Iterator) {
 	select {
 	case cfg.iteratorPool <- iter:
 		return