seborama / Fuego

ƒuego - Functional Experiment in Go

Table of content

• Overview
• Documentation
• Installation
• Example Stream
• Contributions
• The Golden rules of the game
• Pressure
• Concept: Entry
• Features summary
  • Concurrency
• Collectors
• Known limitations

Overview

Making Go come to functional programming.

This is a research project in functional programming which I hope will prove useful!

ƒuego brings a few functional paradigms to Go. The intent is to save development time while promoting code readability and reduce the risk of complex bugs.

I hope you will find it useful!

Have fun!!

(toc)

Documentation

The code documentation and some examples can be found on godoc.

The tests form the best source of documentation. ƒuego comes with a good collection of unit tests and testable Go examples. Don't be shy, open them up and read them and tinker with them!

Note:
Most tests use unbuffered channels to help detect deadlocks. In real life scenarios, it is recommended to use buffered channels for increased performance.

(toc)

Installation

Download

go get github.com/seborama/fuego

Or for a specific version:

go get gopkg.in/seborama/fuego.v8

Import in your code

You can import the package in the usual Go fashion.

To simplify usage, you can use an alias:

package sample

import ƒ "gopkg.in/seborama/fuego.v8"

...or import as an unqualified dot import:

package sample

import . "gopkg.in/seborama/fuego.v8"

(toc)

Example Stream

    strs := EntrySlice{
        EntryString("a"),
        EntryString("bb"),
        EntryString("cc"),
        EntryString("ddd"),
    }
    
    NewStreamFromSlice(strs, 500).
        Filter(isEntryString).
        Distinct().
        Collect(
            GroupingBy(
                stringLength,
                Mapping(
                    stringToUpper,
                    Filtering(
                        stringLengthGreaterThan(1),
                        ToEntrySlice()))))
    }

    // result: map[1:[] 2:[BB CC] 3:[DDD]]

(toc)

Contributions

Contributions and feedback are welcome.

For contributions, you must develop in TDD fashion and ideally provide Go testable examples (if meaningful).

If you have an idea to improve ƒuego, please share it via an issue. And if you like ƒuego give it a star to show your support for the project - it will put a smile on my face! 😊

Thanks!!

(toc)

The Golden rules of the game

1. Producers close their channel. In other words, when you create a channel, you are responsible for closing it. Similarly, whenever ƒuego creates a channel, it is responsible for closing it.

2. Consumers do not close channels.

3. Producers and consumers should be running in separate Go routines to prevent deadlocks when the channels' buffers fill up.

(toc)

Pressure

Go channels support buffering that affects the behaviour when combining channels in a pipeline.

When the buffer of a Stream's channel of a consumer is full, the producer will not be able to send more data through to it. This protects downstream operations from overloading.

Presently, a Go channel cannot dynamically change its buffer size. This prevents from adapting the stream flexibly. Constructs that use 'select' on channels on the producer side can offer opportunities for mitigation.

(toc)

Concept: Entry

Entry is inspired by hamt.Entry. This is an elegant solution from Yota Toyama: the type can be anything so long as it respects the simple behaviour of theEntry interface. This provides an abstraction of types yet with known behaviour:

• Hash(): identifies an Entry Uniquely.
• Equal(): defines equality for a concrete type of Entry. Equal() is expected to be based on Hash() for non-basic types. Equal should ensure the compared Entry is of the same type as the reference Entry. For instance, EntryBool(false) and EntryInt(0) both have a Hash of 0, yet they aren't equal.

Several Entry implementations are provided:

• EntryBool
• EntryInt
• EntryFloat
• EntryString
• EntryMap
• EntrySlice
• Tuples

Check the godoc for additional methods each of these may provide.

(toc)

Features summary

Streams:

• Stream
• IntStream
• FloatStream
• CStream - concurrent implementation of Stream

Functional Types:

• Maybe
• Tuple
• Predicate:
  • True
  • False
  • FunctionPredicate

Functions:

• Consumer
• Function:
  • ToIntFunction
  • ToFloatFunction
• BiFunction
• StreamFunction:
  • FlattenEntrySliceToEntry
• Predicate:
  • Or
  • Xor
  • And
  • Not / Negate

Collectors:

• GroupingBy
• Mapping
• FlatMapping
• Filtering
• Reducing
• ToEntrySlice
• ToEntryMap
• ToEntryMapWithKeyMerge

Check the godoc for full details.

(toc)

Concurrency

As of v8.0.0, a new concurrent model offers to process a stream concurrently while preserving order.

This is not possible yet with all Stream methods but is available with e.g. Stream.Map.

Notes on concurrency

Concurrent streams are challenging to implement owing to ordering issues in parallel processing. At the moment, the view is that the most sensible approach is to delegate control to users. Multiple ƒuego streams can be created and data distributed across as desired. This empowers users of ƒuego to implement the desired behaviour of their pipelines.

Stream has some methods that fan out (e.g. ForEachC). See the godoc for further information and limitations.

I recommend Rob Pike's slides on Go concurrency patterns:

• Go Concurrency Patterns, Rob Pike, 2012

As a proof of concept and for facilitation, ƒuego has a CStream implementation to manage concurrently a collection of Streams.

(toc)

Collectors

A Collector is a mutable reduction operation, optionally transforming the accumulated result.

Collectors can be combined to express complex operations in a concise manner.
Simply put, a collector allows creating custom actions on a Stream.

ƒuego exposes a number of functional methods such as MapToInt, Head, LastN, Filter, etc...
Collectors also provide a few functional methods.

But... what if you need something else? And it is not straighforward or readable when combining the existing methods ƒuego offers?

Enters Collector: implement you own requirement functionally!
Focus on what needs doing in your streams (and delegate the details of the how to the implementation of your Collector).

(toc)

Known limitations

• several operations may be memory intensive or poorly performing.

(toc)