Skip to content
This repository has been archived by the owner on Nov 26, 2023. It is now read-only.

Commit

Permalink
add readme
Browse files Browse the repository at this point in the history
  • Loading branch information
davidmdm committed Oct 20, 2023
1 parent 3373845 commit 6c07d56
Showing 1 changed file with 62 additions and 0 deletions.
62 changes: 62 additions & 0 deletions readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# xcontext

The `xcontext` package is a Go library that enhances the capabilities of the standard `context` package by adding signal-based context cancellation. This functionality allows you to cancel a context when specific signals are received, such as interrupt signals (e.g., SIGINT) or termination signals (e.g., SIGTERM). The package is particularly useful in applications where graceful shutdown or cleanup is required in response to system signals.

## Installation

You can easily add the `xcontext` package to your Go project using the following go get command:

```bash
go get github.com/davidmdm/xcontext
```

## Usage

### `WithSignalCancelation`

Here is a simple example of how to use the `xcontext` package to gracefully handle SIGINT (Ctrl+C) and SIGTERM (termination signal) in your application:

```go
package main

import (
"context"
"fmt"
"os"
"os/signal"
"syscall"

"github.com/davidmdm/xcontext"
)

func main() {
// Create a context that cancels on SIGINT and SIGTERM signals
ctx, cancel := xcontext.WithSignalCancelation(context.Background(), sycall.SIGINT, syscall.SIGTERM)
defer canel()

// Will be done once context is canceled by a SIGINT
<-ctx.Done()

context.Err() // context.Canceled
context.Cause(ctx) // xcontext.SignalContextError -> context canceled: signal received: interrupt
context.SignalCause(ctx) // syscall.SIGINT (the received signal value)
}
```

In this example, the application uses the `WithSignalCancelation` function to create a context that cancels when either SIGINT or SIGTERM is received.

### `SignalCancelError`

The `SignalCancelError` is a custom error type defined in this package. When a context is canceled due to a signal, this error is used as the context cause, providing information about the signal received. You can use this error type to handle signal-related errors in your code.

### `SignalCause`

The `SignalCause` function allows you to retrieve the signal that caused a context to be canceled. If the context was canceled due to a signal, it returns the signal; otherwise, it returns `nil`. This can be helpful if you want to log or handle the specific signal that triggered the context cancellation.

## Contribution

If you want to contribute to this package or report any issues, please visit the GitHub repository at [https://github.com/davidmdm/xcontext](https://github.com/davidmdm/xcontext).

## License

This package is open source and is provided under the [MIT License](https://github.com/davidmdm/xcontext/blob/main/LICENSE).

0 comments on commit 6c07d56

Please sign in to comment.