a better doc

This commit is contained in:
Xing Xing 2013-12-25 18:11:01 +08:00
parent 02e6bfebcb
commit 298edadfa6
2 changed files with 41 additions and 41 deletions

View File

@ -11,8 +11,8 @@ and getting responses from the server.
import "github.com/mikespook/gearman-go/client"
The worker package will help developers in developing Gearman worker
service easily.
The worker package will help developers to develop Gearman's worker
in an easy way.
import "github.com/mikespook/gearman-go/worker"
*/

View File

@ -1,3 +1,5 @@
// The worker package helps developers to develop Gearman's worker
// in an easy way.
package worker
import (
@ -14,24 +16,8 @@ const (
Immediately = 0
)
/*
Worker side api for gearman
usage:
w = worker.New(worker.Unlimited)
w.AddFunction("foobar", foobar)
w.AddServer("127.0.0.1:4730")
w.Work() // Enter the worker's main loop
The definition of the callback function 'foobar' should suit for the type 'JobFunction'.
It looks like this:
func foobar(job *Job) (data []byte, err os.Error) {
//sth. here
//plaplapla...
return
}
*/
// Worker is the only structure needed by worker side developing.
// It can connect to multi-server and grab jobs.
type Worker struct {
sync.Mutex
agents []*agent
@ -39,14 +25,19 @@ type Worker struct {
in chan *inPack
running bool
Id string
// assign a ErrFunc to handle errors
Id string
ErrorHandler ErrorHandler
JobHandler JobHandler
limit chan bool
}
// Get a new worker
// Return a worker.
//
// If limit is set to Unlimited(=0), the worker will grab all jobs
// and execute them parallelly.
// If limit is greater than zero, the number of paralled executing
// jobs are limited under the number. If limit is assgined to
// OneByOne(=1), there will be only one job executed in a time.
func New(limit int) (worker *Worker) {
worker = &Worker{
agents: make([]*agent, 0, limit),
@ -59,15 +50,16 @@ func New(limit int) (worker *Worker) {
return
}
//
// inner error handling
func (worker *Worker) err(e error) {
if worker.ErrorHandler != nil {
worker.ErrorHandler(e)
}
}
// Add a server. The addr should be 'host:port' format.
// The connection is established at this time.
// Add a Gearman job server.
//
// addr should be formated as 'host:port'.
func (worker *Worker) AddServer(net, addr string) (err error) {
// Create a new job server's client as a agent of server
a, err := newAgent(net, addr, worker)
@ -78,9 +70,7 @@ func (worker *Worker) AddServer(net, addr string) (err error) {
return
}
// Write a job to job server.
// Here, the job's mean is not the oraginal mean.
// Just looks like a network package for job's result or tell job server, there was a fail.
// Broadcast an outpack to all Gearman server.
func (worker *Worker) broadcast(outpack *outPack) {
for _, v := range worker.agents {
v.write(outpack)
@ -88,8 +78,7 @@ func (worker *Worker) broadcast(outpack *outPack) {
}
// Add a function.
// Plz added job servers first, then functions.
// The API will tell every connected job server that 'I can do this'
// Set timeout as Unlimited(=0) to disable executing timeout.
func (worker *Worker) AddFunc(funcname string,
f JobFunc, timeout uint32) (err error) {
worker.Lock()
@ -104,7 +93,7 @@ func (worker *Worker) AddFunc(funcname string,
return
}
// inner add function
// inner add
func (worker *Worker) addFunc(funcname string, timeout uint32) {
outpack := getOutPack()
if timeout == 0 {
@ -135,7 +124,7 @@ func (worker *Worker) RemoveFunc(funcname string) (err error) {
return
}
// inner remove function
// inner remove
func (worker *Worker) removeFunc(funcname string) {
outpack := getOutPack()
outpack.dataType = CANT_DO
@ -143,6 +132,7 @@ func (worker *Worker) removeFunc(funcname string) {
worker.broadcast(outpack)
}
// inner package handling
func (worker *Worker) handleInPack(inpack *inPack) {
switch inpack.dataType {
case NO_JOB:
@ -168,6 +158,8 @@ func (worker *Worker) handleInPack(inpack *inPack) {
}
}
// Connect to Gearman server and tell every server
// what can this worker do.
func (worker *Worker) Ready() (err error) {
for _, v := range worker.agents {
if err = v.Connect(); err != nil {
@ -180,11 +172,17 @@ func (worker *Worker) Ready() (err error) {
return
}
// Main loop
// Main loop, block here
// Most of time, this should be evaluated in goroutine.
func (worker *Worker) Work() {
defer func() {
for _, a := range worker.agents {
a.Close()
}
}()
worker.running = true
for _, v := range worker.agents {
v.Grab()
for _, a := range worker.agents {
a.Grab()
}
var inpack *inPack
for inpack = range worker.in {
@ -192,7 +190,7 @@ func (worker *Worker) Work() {
}
}
// job handler
// custome handling warper
func (worker *Worker) customeHandler(inpack *inPack) {
if worker.JobHandler != nil {
if err := worker.JobHandler(inpack); err != nil {
@ -201,13 +199,13 @@ func (worker *Worker) customeHandler(inpack *inPack) {
}
}
// Close.
// Close connection and exit main loop
func (worker *Worker) Close() {
worker.running = false
close(worker.in)
}
// Send a something out, get the samething back.
// Echo
func (worker *Worker) Echo(data []byte) {
outpack := getOutPack()
outpack.dataType = ECHO_REQ
@ -216,7 +214,7 @@ func (worker *Worker) Echo(data []byte) {
}
// Remove all of functions.
// Both from the worker or job servers.
// Both from the worker and job servers.
func (worker *Worker) Reset() {
outpack := getOutPack()
outpack.dataType = RESET_ABILITIES
@ -233,7 +231,7 @@ func (worker *Worker) SetId(id string) {
worker.broadcast(outpack)
}
// Execute the job. And send back the result.
// inner job executing
func (worker *Worker) exec(inpack *inPack) (err error) {
defer func() {
if worker.limit != nil {
@ -277,11 +275,13 @@ func (worker *Worker) exec(inpack *inPack) (err error) {
return
}
// inner result
type result struct {
data []byte
err error
}
// executing timer
func execTimeout(f JobFunc, job Job, timeout time.Duration) (r *result) {
rslt := make(chan *result)
defer close(rslt)