cgc

README

cgc-go: Cross Goroutine Calls library

Package cgc is a package that allows you pass a function for another goroutine to execute it.

It is useful when some logic must be run on a separate thread and you want to wait for the result, or you want to cancel a foreign function with Go's context cancellation mechanism.

The package provides a event queue named Executor. You can make use of Executor to listen to requests from one goroutine, and send requests to it from any other goroutines.

Documentation

Overview

Package cgc is a package that allows you pass a function for another goroutine to execute it.

It is useful when some logic must be run on a separate thread and you want to wait for the result, or you want to cancel a foreign function with Go's context cancellation mechanism.

The package provides a event queue named Executor. You can make use of Executor to listen to requests from one goroutine, and send requests to it from any other goroutines. Please refer to documentations of each function for details.

Index

• func RunOneRequest(ctx context.Context, r *Request)
• type Executor
  • func New() Executor
  • func NewBuffered(bufferLength uint) Executor
  • func (e Executor) RunLoop(ctx context.Context) error
  • func (e Executor) RunOnce(ctx context.Context) error
  • func (e Executor) Submit(ctx context.Context, f Func) (interface{}, error)
  • func (e Executor) SubmitNoWait(ctx context.Context, f Func) error
• type Func
• type Request

Functions

func RunOneRequest

func RunOneRequest(ctx context.Context, r *Request)

RunOneRequest executes on request that is already extracted from an executor.

To extract a request from an executor, use

req := <-executor

This function should be called from the callee goroutine, either ctx or r.Context may cancel the inner function.

Instead of using RunOneRequest, you can also use

executor.RunOnce(ctx)

Types

type Executor

type Executor chan *Request

Executor is a cross-goroutine execution unit.

func New

func New() Executor

New creates a new unbuffered Executor.

func NewBuffered

func NewBuffered(bufferLength uint) Executor

NewBuffered creates a new Executor with specified buffer length.

func (Executor) RunLoop

func (e Executor) RunLoop(ctx context.Context) error

RunLoop keeps executing requests from the executor until ctx is canceled.

This function should be called from the callee goroutine, either ctx or r.Context may cancel the inner function.

Instead of using RunLoop, you can also use

loop:
    for {
        select {
            case req := <-executor:
                cgc.RunOneRequest(ctx, req)
            case <-ctx.Done():
                break loop
            /* case other events: */
        }
    }

manually if the callee goroutine has more things to do than just listening to requests.

func (Executor) RunOnce

func (e Executor) RunOnce(ctx context.Context) error

RunOnce executes one request from the executor.

This function should be called from the callee goroutine, either ctx or r.Context may cancel the inner function.

Instead of using RunOnce, you can also use

req := <-executor
cgc.RunOneRequest(ctx, req)

func (Executor) Submit

func (e Executor) Submit(ctx context.Context, f Func) (interface{}, error)

Submit submits a request to the executor and wait for the result.

This function should be called from the caller goroutine, either ctx or the context at the callee goroutine may cancel the request.

func (Executor) SubmitNoWait

func (e Executor) SubmitNoWait(ctx context.Context, f Func) error

SubmitNoWait submits a request, wait for the request to be received, but does not wait for the result.

This function should be called from the caller goroutine, either ctx or the context at the callee goroutine may cancel the request.

type Func

type Func func(ctx context.Context) (interface{}, error)

Func is a function to submit to another goroutine to execute.

type Request

type Request struct {
	Func    Func
	Context context.Context
	// contains filtered or unexported fields
}

Request is a message body passed from the caller to the callee.