Gowl

Table of Contents

• Install
• How to use
  • Pool
    • Start
    • Register process
    • Kill process
    • Close
  • Monitor
• License

Install

Using Gowl is easy. First, use go get to install the latest version of the library. This command will install the gowl along with library and its dependencies:

go get -u github.com/hamed-yousefi/gowl

Next, include Gowl in your application:

import "github.com/hamed-yousefi/gowl"

How to use

Gowl has three main parts. Process, Pool, and Monitor. The process is the smallest part of this project. The process is the part of code that the developer must implement. To do that, Gowl provides an interface to inject outside code into the pool. The process interface is as follows:

Process interface {
Start(ctx context.Context) error
Name() string
PID() PID
}

The process interface has three methods. The Start function contains the user codes, and the pool workers use this function to run the process. The Name function returns the process name, and the monitor uses this function to provide reports. The PID function returns process id. The process id is unique in the entire pool, and it will use by the pool and monitor.

If properly done it should respond to the context cancellation (if needed)

Let's take a look at an example:

Document struct {
   content string
   hash string
}

func (d *Document) Start(ctx context.Context) error {
   hasher := sha1.New()
   hasher.Write(bv)
   h.hash = base64.URLEncoding.EncodeToString(hasher.Sum(nil))
}

func (d *Document) Name() string {
   return "hashing-process"
}

func (d *Document) PID() PID {
   return "p-1"
}

func (d *Document) Hash() string {
   return h.hash
}

As you can see, in this example, Document implements the Process interface. So now we can register it into the pool.

Pool

Creating Gowl pool is very easy. You must use the NewPool(size int) function and pass the pool size to this function. Pool size indicates the worker numbers in and the underlying queue size that workers consume process from it. Look at the following example:

pool := gowl.NewPool(4)

In this example, Gowl will create a new instance of a Pool object with four workers and an underlying queue with the size of four.

Start

To start the Gowl, you must call the Start() method of the pool object. It will begin to create the workers, and workers start listening to the queue to consume process.

Register process

To register processes to the pool, you must use the Register(args ...process) method. Pass the processes to the register method, and it will create a new publisher to publish the process list to the queue. You can call multiple times when Gowl pool is running.

Kill process

One of the most remarkable features of Gowl is the ability to control the process after registered it into the pool. You can kill a process before any worker runs it, this also works after the job have started if it consideres the context cancellation. Killing a process is simple, and you need the process id to do it.

pool.Kill(PID("p-909"))

Close

Gowl is an infinite worker pool. However, you should have control over the pool and decide when you want to start it, register a new process on it, kill a process, and close the pool and terminate the workers. Gowl gives you this option to close the pool by the Close() method of the Pool object.

Monitor

Every process management tool needs a monitoring system to expose the internal stats to the outside world. Gowl gives you a monitoring API to see processes and workers stats.

You can get the Monitor instance by calling the Monitor() method of the Pool. The monitor object is as follows:

Monitor interface {
   PoolStatus() pool.Status
   Error(PID) error
   WorkerList() []WorkerName
   WorkerStatus(name WorkerName) worker.Status
   ProcessStats(pid PID) ProcessStats
}

The Monitor gives you this opportunity to get the Pool status, process error, worker list, worker status, and process stats. Wis Monitor API, you can create your monitoring app with ease. The following example is using Monitor API to present the stats in the console in real-time.

Also, you can use the Monitor API to show worker status in the console:

License

MIT License, please see LICENSE for details.