DEV Community: Wesley Powell

New Golang Error: Final Update

Wesley Powell — Fri, 21 Jul 2023 00:23:01 +0000

It has been a while since I last posted about better golang error handling and I thought I would follow up with how this ended up in real code.

Final Error Design

The design is largely the same now, but with some naming tweaks and extra functions. I have also ironed out a lot of details regarding error propagation and added some more interesting concepts.

type Cause interface {
    ~uint
}

type Error[T Cause] struct {
    Cause     T
    rootCause any
    Message   string
    // Add as much extra detail as you wish!
}

func NewError[T Cause](ctx context.Context, cause T, message string, values ...any) Error[T] {
    // ...
}

func FromError[T Cause, R Cause](cause T, origin Error[R]) Error[T] {
    // ...
}

func Ok[T Cause]() Error[T] {
    return Error[T]{}
}

// Error message.
//
// Satisfies the error interface.
func (self Error[T]) Error() string {
    return self.String()
}

func (self Error[T]) IsOk() bool {
    return self.Cause == 0
}

func (self Error[T]) IsErr() bool {
    return self.Cause != 0
}

func (self Error[T]) String() string {
    // ...
}

Note that the Error is now simply the transport mechanism for the important piece, the Cause. When handling the Error, we check its Cause to see what caused the function to fail.

When propagating errors, there is now the FromError() option. This allows you to simply take an error from a function and return it as another error for your function. Note that this is just copying data around and there is no linked list behind the scenes. I did find it useful to keep the rootCause as well as the current Cause. That is so that we can log the first Cause while still being able to react to different Causes as we pass the error up the call stack.

One of the nicest benefits of Error over golang's error is that it requires zero heap allocation. As defined above, Error is clearly superior to golang's error in every way. It does exactly what golang can do, but for a fraction of the CPU time and memory allocation. I encourage you to benchmark it yourself.

Note that you can add anything you wish to the Error. It is simply there as metadata for your root cause. If you wish to make your errors heavier, but more descriptive, you could add codes, stack traces, metrics, logging, and more. There is a lot of power you can wield in this simple structure. This is simply a starting point for your project.

Error Usage

Here is an example of it being used.

type MyError uint

const (
    MyErrorInternalFailure = MyError(iota + 1)
    MyErrorNotFound
)

func getThing(ctx context.Context) Error[MyError] {
    if true {
        return NewError(ctx, MyErrorNotFound, "could not find the thing")
    }
    return errors.Ok[MyError]()
}

func main() {
    ctx := context.Background()

    switch getThingErr := getThing(ctx); getThingErr.Cause {
    case MyErrorInternalFailure:
        fmt.Println("failed finding the thing, internal failure: " + getThingErr.Error())
    case MyErrorNotFound:
        fmt.Println("failed finding the thing, not found: " + getThingErr.Error())
    default:
        // Found the thing!
    }
}

When thinking about what error causes to create, think about what is important to test. Each failure case should have its own Cause enum value on the function. For example, a function may return NotFound, InternalFailure, BadRequest, etc. This means you can easily test for different cases. I find that keeping your testing in mind helps guide your coding decisions.

When a consumer handles a NotFound case, it may not care and totally ignore it or it may combine it with another error that the function returns. Regrouping error causes becomes useful in cases where say your storage layer has a bunch of storage specific error cases, like maybe MySqlTransactionFailure, but the calling function just lumps them all into a generic InternalFailure cause that it returns.

Another important point for this pattern is that you only ever have two return values: (<value>, <error>). Any "soft" error where your value may not exist should be contained inside your error cause enumeration. That eliminates the awkward case where you have no value, but no error either and you get the dreaded (in golang errors) (nil, nil), and you have to determine what that actually means. Keeping this you-have-it-or-not approach ensures that your error switchs always handle every possible case and that your default case is purely reserved for your success case and you are guaranteed a value.

A nice side effect of the switch pattern, is that you can often keep your variables with the scope of the switch to avoid mistakenly referencing variables and to keep your code cleaner.

Knowing that you are guaranteed a value and guaranteed those specific failure causes becomes powerful within large applications. When you enable linting (which you should already have!), any new error enum value will highlight your code where you need to handle this new case. When you remove a case, you will get compile errors showing where that case is no longer valid. This makes making business logic changes to large existing applications becomes much easier because your code highlights everything you need to change. It also forces you to think about the new case. Let's say you add a UserNotFound case to a function deep inside your application. If you were using golang errors, then you may add this case and think you have it handled because everything is error and checked with if err != nil. But because each function is typed to its own possible error causes, you are now forced to handle this case in your entire application. This helps eliminate bugs before they even exist! I can attest that I have been pleasantly surprised at how many times this error pattern has saved me from making logical mistakes.

I encourage you to use this sample code and expand on it in your applications for your own needs. Check out the full example on the Go Playground!

Avoid go1.20 Error Handling

Wesley Powell — Mon, 06 Feb 2023 06:39:27 +0000

I have already stated just how bad golang error handling is in Golang Error Handling. This post focuses on the new additions to error handling in go1.20.

My hot take

My opinion remains that error handling provided by golang is not great, but I believe that the new go1.20 additions bring a whole new dimension of issues to the language that are just staggering. To put it bluntly, I have never seen a feature released by a language that actively makes the language worse. This and other bizarre decisions make me deeply concerned for the future of golang. If I ever see errors.Join() or Unwrap() []error in a code review, it will not get my approval.

Pre-go1.20

Let me show an example of the pre-go1.20 state of things just to emphasize the absurdity of these new changes. error is a linked list of any implementation, unknown to the consumer, that just has to satisfy Error() string. Let's take a look at what this would look like if we did not have a nice error word saving face.

// Go Playground: https://go.dev/play/p/f3Xwyv30C4U
type LinkedList struct {
    value any
    next  *LinkedList
}

func New(value any) *LinkedList {
    return &LinkedList{
        value: value,
        next:  nil,
    }
}

func Wrap(value any, currentList *LinkedList) *LinkedList {
    return &LinkedList{
        value: value,
        next:  currentList,
    }
}

func DoWork() *LinkedList {
    if resultLinkedList := addJob(); resultLinkedList != nil {
        return Wrap("DoWork failed", resultLinkedList)
    }

    return nil
}

This is effectively what is happening when you create errors and wrap them in golang. Note: I omitted the linked list traversal. I would be very concerned if someone tried to implement this error pattern in any language. It is complex, error prone, and an anti-pattern. It also leaks implementation details. Any consumer of DoWork() must also know what addJob() does and what its error returns mean. To say otherwise is to ignore the very nature of the linked list. This is not great in itself, but it gets even worse with go1.20.

Enter go1.20

This update introduces two new additions to the errors package:

errors.Join()
Unwrap() []error

This means that we can now specify multiple errors when wrapping. For example: fmt.Errorf("errors: %w, %w", err1, err2). If you notice, this also means that we now have to track multiple errors instead of just one per error instance, which means we have moved from a linked list to a tree of errors. Size and time complexity just increased. Think about the LinkedList example above and how that would become even more complicated.

So what does this even look like in go1.20. Here is a small example.

// Go Playground: https://go.dev/play/p/-iUZt7kSp6-
func externalFn1() error {
    return fmt.Errorf("%w OR %w?", err1, err2)
}

func externalFn2() error {
    return fmt.Errorf("%w OR %w?", err2, err1)
}

func printErr(err error) {
    switch {
    case errors.Is(err, err1):
        fmt.Println("err is err1 - " + err.Error())
    case errors.Is(err, err2):
        fmt.Println("err is err2 - " + err.Error())
    }
}

// printErr(externalFn1())
// prints -> err is err1 - one OR two?
// printErr(externalFn2())
// prints -> err is err1 - two OR one?

This highlights a massive issue with this: the error is both err1 and err2. However, when you check for those, you will never fall into the err2 case because err1 matches first.

Because a function can now return multiple errors, there is no way to determine what the actual error is. How should a developer handle these errors? Maybe one function only has one error but there is the possibility that it could be more than one, so all error handling must account for that case. Maybe one function returns two errors that are meant to be handled in conjunction, like a http status code and the error that caused it, and another function returns multiple errors but certain ones should be handled over overs. There is just no way of knowing without having to read documentation for each function and understand its internal behavior. At that point, what you have is no longer error handling, but a full blown application with business logic, documentation, and various use cases. This is not what we need from our error handling.

One aspect that may not be immediately apparent is that due to golang's rule that functions may not be overloaded, an error type cannot implement both Unwrap() error and Unwrap() []error. That means that if you have a mix of LinkedList errors and Tree errors you are bound to run into trouble. The error type can only implement one version of that function, so any code out there that type asserts for Unwrap() error must now be updated to handle both cases.

To demonstrate this issue, look at the following example and observe that the result of unwrapping the error is nil.

// Go Playground: https://go.dev/play/p/0gVlavnmvJf
err := fmt.Errorf("this is bad: %w, %w", err1, err2)
unwrappedErr := errors.Unwrap(err)
fmt.Println(unwrappedErr) // prints <nil>

As compared to the same code but only wrapping one error.

// Go Playground: https://go.dev/play/p/0gVlavnmvJf
err := fmt.Errorf("this is bad: %w", err1)
unwrappedErr := errors.Unwrap(err)
fmt.Println(unwrappedErr) // prints one

When it comes to performance, it just gets worse. We have no ordering to the error tree here, so we still have O(n) at worse case search. Plus, all of the issues that plagued LinkedList errors still plague Tree errors but now the complexities just increased.

Conclusion and Further Reading

In short, stop. Just do not do it. I guarantee that I have not covered all issues related to Tree errors. There is some great feedback on this approach in various other threads, like this one. Reading through the actual proposal thread for this feature illuminates other issues that I had not even considered yet, like thread safety.

For a straightforward, unbiased post, this blog post explains the new mechanics well.

In my personal opinion, after having actually removed error from an entire application now, we are all better off ignoring error completely along with all changes added to errors in go1.20.

Follow Up: Establishing A Better Pattern

Wesley Powell — Fri, 09 Sep 2022 00:24:31 +0000

Takeaways

Errors as uint64 for better performance
Use enums to define error cases
By convention, 0 is "OK" or "no error"
Use the exhaustive linter with switch
Implement Stringer on enums for human readable error messages
Use generic T ~uint64 to type custom structs to errors

I have been racking my brain trying to figure out a better golang error handling pattern. In my previous posts, I alluded to a potential solution but after some experimentation it was not sufficient. After revisiting and coming back to this topic a few more times, I think I hit on something. The best part is this requires no external dependencies and does not require wholesale conversions to this new pattern.

Defining an Error

Defining what an error is actually gets us to the root of the issue. Usually in golang, an error is a string or a struct that contains a string value. But when something fails in a function, sometimes there really is no reason to return a full human readable string. It can be just as good to return an integer constant that identifies the error.

Performance

Why an integer, though? If we examine error, we can see that it is an interface and therefore using it will cause the value to escape to the heap. That means all errors are heap allocations. While golang utilizes garbage collection, too many heap allocations can cause performance issues across your application. Consider a situation where an application is running nominally and suddenly an influx of errors occur. You would not want a spike in error value allocations to cause an unexpected CPU spike that could potentially ripple through a system. Defining errors as uint64 solves that problem. That will be heap allocation free.

Takeaway: Errors as uint64 for better performance

Case study: context.Context

Let us take Err() error from context.Context as an example. In the function comments, it essentially states that it returns one of:

No error (nil)
var Canceled = errors.New("context canceled")
var DeadlineExceeded error = deadlineExceededError{}

We can already take that description and use it directly in our first new error pattern example.

type ContextError uint64

const (
    Ok ContextError = iota
    Canceled 
    DeadlineExceeded
)

func (c Context) Err() ContextError {
    // Could return this error denoting the Context was canceled.
    return Canceled
    // Or this error denoting the Context deadline passed.
    return DeadlineExceeded
    // Or there is no error.
    return Ok
}

Right away we can see that provides self-documenting code. We know Err() will return a ContextError and that it is defined as one of two values: Ok, Canceled, DeadlineExceeded. This is a huge win already.

Takeaway: Use enums to define error cases

How would we use this? Before, we would use if err != nil or possibly if errors.Is(err, context.Canceled). Instead, we can stick to one single pattern using switch.

switch err := ctx.Err(); err {
case context.Canceled:
    // Handle the case when the Context is canceled.
case context.DeadlineExceeded:
    // Handle the case when the Context deadline has passed.
case context.Ok:
    // There is no error!
}

Let us take a look at what happens here. The switch here acts like a better if-else. We invoke Err() and get an err value and then we switch on err to find the correct case. If there is no error then we just return Ok (which is just 0). Since the type of err is ContextError, we know exactly what errors to handle!

Takeaway: By convention, 0 is "OK" or "no error"

In fact, if you are using the highly recommended linting tool golangci-lint with the exhaustive linter enabled then your IDE will actually warn you when you are missing an error case. And if an error value is ever removed, then you will get a compile error telling you that case is no longer valid. The usage of this pattern is heavily influenced by rust's match operator.

Takeaway: Use the exhaustive linter with switch

Static Error Messages

Sometimes we want to log our errors and uint64 will not cut it. Especially since iota starts over for each const block. Fortunately, golang has already solved this for us as well! Whenever you invoke a Print on a value via fmt.Println(), the log package, or other method, it will attempt to print it based on reflection. There is actually a Stringer interface that golang will check for and use that if the value implements it. This interface looks like this:

// Stringer is implemented by any value that has a String method,
// which defines the “native” format for that value.
// The String method is used to print values passed as an operand
// to any format that accepts a string or to an unformatted printer
// such as Print.
type Stringer interface {
    String() string
}

Using this on an enum is already an established pattern. We can easily attach this to our ContextError:

func (self ContextError) String() string {
    return [...]string{
        "ok",
        "context canceled",
        "context deadline exceeded",
    }[self]
}

Takeaway: Implement Stringer on enums for human readable error messages

Custom Errors

Sometimes we do want to return some context with our errors. In those instances, a uint64 will not cut it. For those cases we can simply create custom error structs that suite our needs. For example, if all we need is a dynamic string to accompany our uint64 error for log printing later, we can do something like this:

// errors/message.go
type Message[T ~uint64] struct {
    Error   T
    Message string
}

func NewMessage[T ~uint64](err T, message string) Message[T] {
    return Message[T]{
        Error:   err,
        Message: message,
    }
}

Using our Context example, we could use this as:

errors.NewMessage(Canceled, "context was canceled by user")

There is a bit going on here. First we have Message[T ~uint64]. This tells us that a Message requires some type whose underlying value is uint64 (~ indicates underlying value). Since Canceled is of type ContextError uint64, that satisfies this type constraint. So what does that give us? Well now we know Error is of type T so when we switch on Message.Error, this functions exactly like our simpler enum example from above. But now that we have this new struct, we can also pull out Message.Message and log it.

Takeaway: Use generic T ~uint64 to type structs to errors

If we want a "no error" case for Message then we could make a helper function:

func Ok[T ~uint64]() Message[T] {
    return Message[T]{}
}

Since the default value of uint64 is 0 and our convention is that 0 is equivalent to "no error" then golang solves this perfectly for us.

What about `error` and the `errors` package?

We simply do not need them anymore. In fact, you could just shadow error in all of your packages: type error uint64, but I would not actually recommend that. It is just more evidence that standard error handling in golang is more like a guideline than an actual rule.

Conclusion

Admittedly, this is not perfect. Returning "no error" is particularly funky. However, what this shows is that we do not need any extra packages to handle fancy stuff in order to get into better golang error handling. Golang already provides everything we need, we just have to define a new convention using those pieces and improve our code.

Left Handed in a Right Handed World

Wesley Powell — Sat, 20 Aug 2022 18:09:48 +0000

About 90% of the human population are right hand dominant ^[wikipedia]. Being left handed in a right handed world has challenges and differences that are not obvious to someone who is right handed. Let me know in the comments about your left handed experiences.

Daily Life

Scissors

Very few people that I have interacted with realize that scissors are the worst thing in the world for left handed use. The reason for this is that right handed scissors are designed with the cutting blade on top and when you squeeze it naturally pushes the blades together. This provides for a sharp clean cut. When used in the left hand the cutting blade flips to the bottom and the squeezing action actually forces the blades apart. Naturally, if the blades are not flush, it will not cut. The solution for left handed use is to change hand posture and consciously torque the blades together as you cut. But obviously, this is incredibly uncomfortable and not very fun to use. If you know someone who is left handed, chances are they have a pair of left handed scissors.

Dinner Table

You sit down for dinner with family, friends, or date. You pick up a fork and start eating, but suddenly you are bumping elbows with the person next to you. This is not unfamiliar to lefties. Because the hand you use to eat with is likely different than those around you, your elbows move in the same space and eventually will collide. This has led lefties to heading this off and looking for the ends of tables where they will have no one to collide with.

In some cultures, eating with your left hand is considered unsanitary and/or rude.

Pens

This is a weird one. Some pens have a twist in the middle to extend the ballpoint. I have never come across a left handed version of these. What happens is that the natural torque of your left hand as you write is opposite from your right hand and using it in your left will actually close the pen as you write.

Computers

If you pick any public computer and sit down at it, chances are the mouse is on the right side. If you are left handed, this means you have to move the mouse to the other side, which could be problematic in small spaces like keyboard trays. It also means that you probably have to flip the primary buttons in the mouse settings. I say "probably" because I lived for a long time using right handed buttons in my left hand simply because it is annoying to change constantly.

A slight advantage I have obtained is the ability to use a mouse in either hand. This has lead me to heading off RSI in my primary mouse hand. Whenever my hand starts to hurt, I just flip my mouse to the other side for a few weeks. I am not as precise in my right hand, but for most tasks it works out just fine.

Cups/Mugs

Depending on your personal preference, you may want to stare at a logo or slogan as you drink your preferred hot beverage. When you drink with your left hand, that flips and you may or may not have your preferred side facing you. This is a small thing, but may become a slight annoyance, or hidden benefit.

PC Gaming

Hardware

When playing PC games, one annoying aspect is that WASD is on the left side of a long keyboard. So when you want to game you have to slide the keyboard so far over to the right that you have to make room or it hangs off the edge of your desk. And if you have it in a keyboard tray then you just have to move it out of the tray. Additionally, if you are gaming on a laptop there is not much you can do.

Another interesting thing is that WASD controls fits your hand differently so pressing certain buttons just doesn't feel right so sometimes you have to remap the buttons. Also, I have used my palm to jump (space bar) my entire life. However, I have never understood why right handed gamers decided to put crouch and sprint (CTRL, SHIFT) under your pinkie, which is one of the most frequent movements controlled by the weakest finger. I have always felt like I have had an advantage there since I can use my thumb and index finger for those controls. But most other actions have you reaching out away from your right hand (G, F, T, V, etc) for things like interact, grenades, and melee which is more natural. As left handed, I have to use my pinkie for those which is a struggle and I mess up quite a bit.

Not to mention, all of the best hardware options are only right handed. In fact, I just ordered a left handed (ambidextrous actually) gaming mouse off of Amazon and the next day the order was canceled due to "lack of availability". Imagine not being able to use your favorite hardware simply because it was not available in your handedness. Imagine reading about a device and getting super excited only to find that you could not use it.

User Interface

Mouse clicks in menus sometimes are hard coded to be right handed. Some of these games are high profile high revenue games like The Elder Scrolls and Rainbow Six: Siege. In games such as these, menus are hard code to right handed even if you change setting in the OS. Fixing this directly in the control mappings does not help since that only affects direct gameplay. Constantly swapping back and forth between button schemes is definitely draining and a frequent source of miss clicks.

Has anyone ever noticed that essentially every game avatar is right handed? It sure would be nice to have an option to flip that and have it be left handed, especially for FPS games. Shout out to, Link, the best left handed avatar out there! We do not talk about Breath of the Wild Link or the Wii.

Firearms

If you have ever shot any side ejecting rifle, you may not realize that if you used it left handed you will get hot bullet casings and gun powder to your arm unless you hold it funky (and potentially unsafe). While not usually an issue you come across very often, I bet being left handed in the military can be rough. I would imagine that not being able to pick up any fellow soldiers firearm and use it without getting burns is an issue.

Left Footed

I am not also left footed but I am aware that there might be extra challenges for those who are. I would be interested to hear about any left footed challenges in the comments! One in particular I have always wondered is if there are any issues with the gas/brake pedals in vehicles.

* All credit and rights for the cover image belong to HuffPost

Better Golang Error Handling

Wesley Powell — Mon, 15 Aug 2022 04:11:12 +0000

TL;DR Skip to the end to see the code

Motivation

I recently reviewed various reasons why the built-in golang error is not great. In fact, if you Google "golang error handling" you will find many other blogs with various takes on how to navigate errors in golang. Even though the topic has seen lots of conversation, there really has not been much progress.

So I will throw out yet another blog post on golang error handling.

Start Fresh

First thing I will propose, though controversial, is to throw out everything there is about golang errors. Do not use error. Do not use the "errors" package. Just throw it all away (it was probably just giving you anxiety anyway). error was more like a guideline anyway.

Now that we have no error handling we are open to a new world of possibilities. What does an error look like? What data should be contained in an error? Once created, how do we handle an error? Can we extend errors now? In this blog, I propose an error of the simplest possible terms so that it may be extended only as needed.

The `Error` Type

type Error[T ~string] string

Yep. Let us just start with a new type called Error. Note that we could also just reuse error since it is not a keyword, but that gets slightly messy. This new Error is simply just a string. string is a great starting point because errors messages are usually strings that are human readable.

Right away, we essentially have everything we need. An error could be "whoops" and no error would be "" (empty string). To make the usage around this a bit nicer to read, we can attach IsSome() bool and IsNone() bool. These two helper functions would just check if the value is "".

For example:

// Create an error
err := errors.New[string]("whoops")

// Handle the error.
if err.IsSome() {
    // Do something useful with the error.
}

While this sufficiently covers creating errors and error handling, there is more that we can do. In fact, while these helper functions may remain on a possible real implementation, I would propose never using them. The reason? There is actually an even better approach that utilizes that generic T on the Error type.

Error Enums

One major issue with golang is the lack of enums. However, there are ways to make enums that linters will recognize. This usually follows in the form of:

const EnumType <some type>

const (
    EnumTypeA = EnumType(<some value>)
    EnumTypeB = EnumType(<some value>)
    // ... and so on
)

Taking some inspiration from rust, it would be amazing if we could have something similar to match that would force us to cover all enum cases. Fortunately, the next best thing is the exhaustive linter.

In the current version of golang error, the only way to create a sentinel error is to do var ErrMyError = errors.New("whoops"). But there is a problem with this: it is a variable, not constant. So this is not a real fake enum that linters recognize. It also does not make sense for these to be mutable globals.

The proposed new Error type solves this issue by accepting a T ~string. This means the type of the Error itself is different depending on T. T is also constrained to ~string which means two things: T can be cast to string, T can be const. Note that even though T is not stored as a value in the Error type, we can still reference it because it is part of the type definition. This allows us to keep Error as a simple string while being able to cast it into T. Taking some more inspiration from rust, we can add a function to Error that does this:

func (self Error[T]) Into() T {
    return T(self)
}

While this all feel like over-complicated code since it is all just syntax sugar around string, it enables us to now have error handling like this:

switch err := StringError(0); err.Into() {
default:
    fmt.Println(err)
case errors.ErrNone:
    fmt.Println("no error")
}

For a simple Error[string], default catches an error if it exists and case errors.ErrNone catches the "no error" case. However, if we have an error enum then that enum type is the T and Into() T returns the error of that type. This looks like:

_, err = EnumError(3)
switch err.Into() {
case ErrMyErrorOne:
    fmt.Println(err)
case ErrMyErrorTwo:
    fmt.Println(err)
case ErrMyErrorThree:
    fmt.Println(err)
case errors.ErrNone:
    fmt.Println("no error")
}

Notice there is a case for each enum that was defined and there is no default. Technically, to be thorough default should be included but if you have to return an error of a certain type then that should not happen, but it could.

What about missing cases? If there is a missing case, the exhaustive linter will point it out and let you know that you did not include everything.

Extending `Error`

The golang error will let you extend it and do whatever you want and any viable replacement should allow the same functionality. It very well may be that a string is not sufficient for some use cases. In that case, we still need a way of extending Error without having to change the pattern.

Let us assume that we desire a unique error code for tracking/debugging purposes that is assigned to each Error. We can extend Error by creating our new type MyError[T ~string] struct and embedding Error in it. MyError now has access to the same functionality that Error does while also having the benefit of storing an extra value for an error ID.

type MyError[T ~string] struct {
    errors.Error[T]

    // Other data defined here.
    errId int
}

func New[T ~string](err T, errId int) MyError[T] {
    return MyError[T]{
        Error: errors.New(err),
        errId: errId,
    }
}

The usage is exactly the same except MyError[T] is returned from a function instead of Error[T].

Advantages/Benefits

So why go through all this effort? Maybe you are satisfied with golang error and need more convincing? Aside from what has already been stated in the sections above, there are more benefits gained from this proposed approach.

Performance

The proposed Error is actually more performant than error. This is because error is an interface which means that literally every error ever created requires a memory allocation. In straight up benchmark comparisons, this is not all that much, but all of those allocations add up.

Here is my non-official benchmark comparison between creating a new golang error and an Error.

error
24.96 ns/op       16 B/op          1 allocs/op
Error
5.557 ns/op        0 B/op          0 allocs/op

A ~4.5x improvement is not too shabby even though we are talking about nanoseconds here.

Self Documenting Code

Documentation is always a struggle. The moment code changes, the documentation must be updated. However, using enums as types in Error allows us to clearly see what errors a function returns. I have used some comments like this before but it just does not feel great:

// Foo does stuff
//
// Errors:
//   * ErrFooFailure
func Foo() error { ... }

Instead, we can now have something like this:

type SampleError string

const (
    ErrMyErrorOne   = SampleError("error one")
    ErrMyErrorTwo   = SampleError("error two")
    ErrMyErrorThree = SampleError("error three")
)

func EnumError(which int) (int, errors.Error[SampleError]) {
    switch which {
    case 1:
        return 1, errors.New(ErrMyErrorOne)
    case 2:
        return 2, errors.New(ErrMyErrorTwo)
    case 3:
        return 3, errors.New(ErrMyErrorThree)
    default:
        return 0, errors.None[SampleError]()
    }
}

This is clear, ties in with the compiler, and is easy to understand. The code simply documents itself.

"Accept interfaces, return structs"

This is a general rule in golang code, but error completely breaks this since it is an interface. Once returned, there is no way to operate on the error except through helper functions like errors.As(). Being required to call Unwrap(), errors.As(), etc means there is uncertainty, which usually leads to bugs. The uncertainty I am referring to is all of the issues mentioned in my previous post, such as error formatting. Since Error is not an interface, we can operate on it with certainty.

No Wrapping

This touches on another small performance benefit. When "errors" was abandoned for this proposal, we also dumped all of that error wrapping insanity. error is used as a linked list. Since Error is intended to be immutable and "one shot", there is no chain of errors that must be traversed to check if we got some type of error. And with the recent release of go1.19, if you happened to have a large set of errors then the proposed switch error handling pattern would benefit from a switch jump table.

Next Steps

This is proposal is something I am still flushing out, but I feel like it shows real promise. In fact, in just writing this I changed a few things, but the core concept remains. I will keep iterating and experimenting my personal projects, though it may take some some convincing to use an iteration of this in actual projects.

TL;DR Just Show Me The Code!

error.go

package errors

import (
    "fmt"
)

const ErrNone = ""

func None[T ~string]() Error[T] {
    return Error[T]("")
}

func New[T ~string](format T, values ...any) Error[T] {
    return newError(format, values...)
}

type Error[T ~string] string

func newError[T ~string](format T, values ...any) Error[T] {
    var err string
    if len(values) != 0 {
        // Do not call fmt.Sprintf() if not necessary.
        // Major performance improvement.
        // Only necessary if there are any values.
        err = fmt.Sprintf(string(format), values...)
    } else {
        err = string(format)
    }

    return Error[T](err)
}

func (self Error[T]) IsNone() bool {
    return self == ""
}

func (self Error[T]) IsSome() bool {
    return !self.IsNone()
}

func (self Error[T]) Into() T {
    return T(self)
}

error_example_test.go

package errors_test

import (
    "fmt"

    "experimentation/errors"
)

func StringError(which int) errors.Error[string] {
    switch which {
    case 1:
        return errors.New("error: %s", "whoops")
    default:
        return errors.None[string]()
    }
}

func ExampleStringError() {
    switch err := StringError(0); err.Into() {
    default:
        fmt.Println(err)
    case errors.ErrNone:
        fmt.Println("no error")
    }

    switch err := StringError(1); err.Into() {
    default:
        fmt.Println(err)
    case errors.ErrNone:
        fmt.Println("no error")
    }

    // Output:
    // no error
    // error: whoops
}

type SampleError string

const (
    ErrMyErrorOne   = SampleError("error one")
    ErrMyErrorTwo   = SampleError("error two")
    ErrMyErrorThree = SampleError("error three")
)

func EnumError(which int) (int, errors.Error[SampleError]) {
    switch which {
    case 1:
        return 1, errors.New(ErrMyErrorOne)
    case 2:
        return 2, errors.New(ErrMyErrorTwo)
    case 3:
        return 3, errors.New(ErrMyErrorThree)
    default:
        return 0, errors.None[SampleError]()
    }
}

func ExampleEnumError() {
    _, err := EnumError(0)
    switch err.Into() {
    default:
        fmt.Println(err)
    case errors.ErrNone:
        fmt.Println("no error")
    }

    _, err = EnumError(3)
    switch err.Into() {
    case ErrMyErrorOne:
        fmt.Println(err)
    case ErrMyErrorTwo:
        fmt.Println(err)
    case ErrMyErrorThree:
        fmt.Println(err)
    case errors.ErrNone:
        fmt.Println("no error")
    }

    // Output:
    // no error
    // error three
}

type MyError[T ~string] struct {
    errors.Error[T]

    // Other data defined here.
    errId int
}

func New[T ~string](err T, errId int) MyError[T] {
    return MyError[T]{
        Error: errors.New(err),
        errId: errId,
    }
}

func (self MyError[T]) String() string {
    return fmt.Sprintf("error: %s, id: %d", self.Error, self.errId)
}

func MyErrorFn() MyError[string] {
    return New("whoops", 123)
}

func ExampleMyError() {
    switch err := MyErrorFn(); err.Into() {
    default:
        fmt.Println(err)
    case errors.ErrNone:
        fmt.Println("no error")
    }

    // Output:
    // error: whoops, id: 123
}

Golang 'error': Everything you know is wrong

Wesley Powell — Thu, 04 Aug 2022 04:45:38 +0000

"errors as linked lists"

The Attempted Concept

The concept of errors as linked lists seems neat at first. You can define your own error type, customize how it prints, and add extra information to it. Once instantiated, you can simply pass it up to the caller as a normal old error. Callers of your function can then check to see if your error Is() another. Cool! Further even, you can add extra info to an error that you wrap and bubble up. Awesome! error is so flexible and powerful!

`error` Chain Of Pain

You start setting up error handling in your first golang application and you find that you start running into problems. You find that you cannot both return an error that Is() both your custom error and the error you just received. "That's fine", you think to yourself, "I should not have the caller rely on my implementation details anyway". So you return your API's own error and move on.

You then start working with some HTTP helper library that returns an error if a request fails. Suddenly, you realize that you also need to know if that error Is() a context.DeadlineExceeded from the request timing out. "That's fine", you think again, "I know how to handle that!". That is when you realize that the DeadlineExceeded error most likely originates from deep within that call stack and you would be relying on their implementation details. Even worse, you realize, "What if the library I am using does not bubble up that error, just as I did earlier? After all, that library could be catching it and returning their own errors too, or worse, that library calls yet another one that does". Suddenly, you realize that everything you knew and trusted about golang errors is wrong. You can no longer trust the error chain to provide reliable consistent results from Is().

`error` Format Catastrophe

I would suggest reading this blog about the catastrophe of golang error printing. This blog discusses yet another failure of the golang error pattern, that if you have a chain of errors and if any of them do not implement Unwrap() error (an optional interface implementation for errors), then your whole chain breaks down. It also goes into detail about the issue of calling Format() on the error chain.

`error` Handling Problems

One issue that many golang devs might not realize is that errors are constantly being shadowed. This is not usually a problem because once an error is encountered, generally, the function returns. Consider the following:

if fooResult, err := foo(); err != nil {
    if barResult, err := bar(); err != nil { // err shadows previous err
        ...
    }
}

The err returned by bar() shadows the err returned by foo(). This is probably not going to cause any problems but you do end up with two instances of err in the same function. Anytime you have shadowed variables it is a code smell. Unfortunately, that means all of golang error handling smells.

Side note: golang gets away with this because it makes an exception on the := operator that if at least one variable is newly declared, then it is fine. That is why you can redeclare err constantly. It just bends the rules a bit to fit the pattern, but causes variable shadowing in the process.

The only way to solve this is by not shadowing those variables, but the solution is not pretty to read:

var fooResult struct{}
var err error
if fooResult, err = foo(); err != nil {
    var barResult struct{}
    if barResult, err = bar(); err != nil {
        ...
    }
}

So the solution is to declare your variables before assignment. Following that train of thought, if you think this issue is solved with named returns, think again. Let's take this example:

func task() (err error) {
    if err = foo(); err != nil {
        if err := bar(); err != nil {
            ...
        }
    }
    return
}

Whoops! You just typo-ed that := on bar(). The compiler says,👍. The function works. But only foo() errors will ever be returned. This is a logic bug, plain and simple. It is easy to fix, but could be difficult to find.

The "Solution"

How do you solve these problems? Short answer: you don't. At least, not without changing the core golang pattern and probably having a few debates with your coworkers about best practices. This is a problem the language itself must address.

Experimental Alternative

Frustrations with error has led me to the propose following changes (that you can try right now!):

Abandon error and never look back
- errors package becomes dead code as a result
- fmt directive "%w" can go away too
Make a type Error struct {}
Make errors values, not references
type error Error, for good measure
- Yes, you can do that. Get that thing outta here!
Make a type Result[T any] struct {}

Now you can live in golang free of the burdens of the built in error interface. For example:

func task() Result[int] {
    fooResult := foo()
    if !fooResult.IsOk() {
        return fooResult
    }

    barResult := bar()
    if !barResult.IsOk() {
        return Err[int](barResult.Error())
    }

    return Ok(1)
}

func foo() Result[int] {
    return Ok(2)
}

func bar() Result[float32] {
    return Err[float32]("whoops")
}

Goplay

This is a horrible example, but it demonstrates that you can easily change error handling for the better. Technically, this will impact consumers of this package who use golang error, but the issues this will cause are same that exist already. Broken Unwrap() error chains. Poor formatting standards. Leaking implementation details. You get the idea.

If you noticed, this proposed pattern solves the issues noted in the above section. Errors are values (no wrapping involved), so no more weird chaining issues. Error printing is reliable since there is a defined error struct. Each function or package can define explicit Errors as part of its API that can be checked for by equivalence, not by Is() chain detection. Result is a single value, so no more shadowed variables. If you want to add more info to your errors, you could embed Error in your own type ApiError struct {}.

A surprise benefit of this new pattern is that your errors no longer automatically escape to the heap (hint: error is an interface). That's right. Not only is this pattern easier to use and solves the issues of standard golang errors, but it is more performant.

More work obviously needs to be put into this before it can be useful in an actual project, but this is definitely a great start.

Golang Concurrency Jump Start

Wesley Powell — Wed, 20 Jul 2022 03:55:14 +0000

Takeaways In This Post

Only store primitives and immutable or read only values in Contexts
Do not use Context to store application logic values
Always create a main cancellable Context to allow goroutines to gracefully stop
Check Context cancellation before and during long running tasks
Use channels to logically partition concurrent work
Do not communicate by sharing memory; instead, share memory by communicating

Context

A context.Context is a reference (because it is an interface) to an immutable key/value pair that is one node in a tree of Contexts. Each Context can lookup values using the recursive function Value(key) any and check cancellation of the chain with Done() <-chan struct{}. This structure allows values and cancel signals to be shared amongst numerous goroutines. This allows data to be shared safely. One major use case is profiling.

Common Context Pitfalls

Context is commonly abused and misused by allowing values stored in the Context to be mutable and also by storing Contexts inside structs. Both of these mistakes lead to potential race conditions and other issues. Avoid storing maps, slices, references, and channels as Context values. Stick to primitives and struct values. Beware of references stored in struct values as those may also present race condition issues.

Takeaway: Only store primitives and immutable or read only values in Contexts

Another issue is the tendency to use Context as a grab bag of application values. Keep in mind that the more values stored in the Context the longer look ups become, O(n). This pattern also makes debugging difficult since all of the values are "hidden". Pass the values you require as arguments.

Takeaway: Do not use Context to store application logic values

A good practice to follow is always create an application Context before anything else. This allows the main to gracefully shutdown any running goroutines before exiting. Otherwise, goroutines will be halted mid-execution without any opportunity to stop.

Hello, Concurrency!

Basic "Hello, World!" main for concurrency.

func main() {
    ctx, cancel := context.WithCancel(context.Background())

    // Do parallel work...
    go task(ctx)

    cancel()
    time.Sleep(5 * time.Second)
}

goplay

There are improvements that should be done, but this will allow you to spawn any number of goroutines and allow five seconds for those to stop.

Takeaway: Always create a main cancellable Context to allow goroutines to gracefully stop

Of course, goroutines do not simply stop by themselves. They have to monitor their Context for cancellations. A good way to do this is using select. This will block until one of the case branches becomes available.

func task(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            // Context cancelled. Should now stop processing work.
            return
        default:
            // Process work
        }
    }
}

goplay

This function will run until its Context is cancelled. Because default is always available, this will check the Done() channel for a value first and if nothing is ready then it will execute the default branch. Even if a task is not continuously running, it is always a good idea to check the Context before performing an expensive operation, such as a database query.

Takeaway: Check Context cancellation before and during long running tasks

Data Concurrency

When data needs to be accessed by the same goroutine, it is very easy to wrap that data in a sync.Mutex and call it a day. This can lead to complex code and deadlocks. Golang provides a better way of communicating data between goroutines in the form of channels. You can think of channels like a hand off of data from one goroutine to another. That hand off blocks on both ends until both sides are ready.

This pattern does a few things for you:

Guarantees only one process is modifying data at a time
Provides logical partitions of work that are easy to understand
Decouples code that would otherwise rely on specific mutexes


func readPacket(ctx context.Context, packetChannel chan Packet) {
    for {
        select {
        case <-ctx.Done():
            // Context cancelled. Should now stop processing work.
            return
        case packet, ok := <-packetChannel:
            if !ok {
                return
            }

            packet.ReadCount++
            packetChannel <- packet
        }

        time.Sleep(time.Millisecond)
    }
}

goplay

readPacket() continuously checks the channel for new Packets, reads it, and then dumps it back onto the channel for another goroutine to process. If the channel is ever closed then we should stop. ok becomes false once this happens. The small sleep in such a fast looping goroutine like this one allows time for other goroutines to process and prevents the CPU from maxing.

Instead of taking a Packet blocking on mutex associated with it, we can freely pass the Packet between goroutines. The goroutine is an isolated slice of work to be done on the Packet. There may be other operations performing work on it in other goroutines, but those would never impact the thread safety of this goroutine task.

Takeaway: Use channels to logically partition concurrent work

Takeaway: Do not communicate by sharing memory; instead, share memory by communicating

DEV Community: Wesley Powell

New Golang Error: Final Update

Final Error Design

Error Usage

Avoid go1.20 Error Handling

My hot take

Pre-go1.20

Enter go1.20

Conclusion and Further Reading

Follow Up: Establishing A Better Pattern

Takeaways

Defining an Error

Performance

Case study: context.Context

Static Error Messages

Custom Errors

What about error and the errors package?

Conclusion

Left Handed in a Right Handed World

Daily Life

Scissors

Dinner Table

Pens

Computers

Cups/Mugs

PC Gaming

Hardware

User Interface

Firearms

Left Footed

Better Golang Error Handling

Motivation

Start Fresh

The Error Type

Error Enums

Extending Error

Advantages/Benefits

Performance

Self Documenting Code

"Accept interfaces, return structs"

No Wrapping

Next Steps

TL;DR Just Show Me The Code!

Golang 'error': Everything you know is wrong

"errors as linked lists"

The Attempted Concept

error Chain Of Pain

error Format Catastrophe

error Handling Problems

The "Solution"

Experimental Alternative

Golang Concurrency Jump Start

Takeaways In This Post

Context

Common Context Pitfalls

Hello, Concurrency!

Data Concurrency

What about `error` and the `errors` package?

The `Error` Type

Extending `Error`

`error` Chain Of Pain

`error` Format Catastrophe

`error` Handling Problems