Add comments about calling Submit()/Invoke() from Submit()/Invoke()

Fixes #197

pool.go

@@ -49,7 +49,7 @@ type Pool struct {
 	// state is used to notice the pool to closed itself.
 	state int32
 
-	// cond for waiting to get a idle worker.
+	// cond for waiting to get an idle worker.
 	cond *sync.Cond
 
 	// workerCache speeds up the obtainment of a usable worker in function:retrieveWorker.
@@ -142,6 +142,11 @@ func NewPool(size int, options ...Option) (*Pool, error) {
 // ---------------------------------------------------------------------------
 
 // Submit submits a task to this pool.
+//
+// Note that you are allowed to call Pool.Submit() from the current Pool.Submit(),
+// but what calls for special attention is that you will get blocked with the latest
+// Pool.Submit() call once the current Pool runs out of its capacity, and to avoid this,
+// you should instantiate a Pool with ants.WithNonblocking(true).
 func (p *Pool) Submit(task func()) error {
 	if p.IsClosed() {
 		return ErrPoolClosed

pool_func.go

@@ -159,6 +159,11 @@ func NewPoolWithFunc(size int, pf func(interface{}), options ...Option) (*PoolWi
 //---------------------------------------------------------------------------
 
 // Invoke submits a task to pool.
+//
+// Note that you are allowed to call Pool.Invoke() from the current Pool.Invoke(),
+// but what calls for special attention is that you will get blocked with the latest
+// Pool.Invoke() call once the current Pool runs out of its capacity, and to avoid this,
+// you should instantiate a PoolWithFunc with ants.WithNonblocking(true).
 func (p *PoolWithFunc) Invoke(args interface{}) error {
 	if p.IsClosed() {
 		return ErrPoolClosed
@@ -176,7 +181,7 @@ func (p *PoolWithFunc) Running() int {
 	return int(atomic.LoadInt32(&p.running))
 }
 
-// Free returns a available goroutines to work, -1 indicates this pool is unlimited.
+// Free returns an available goroutines to work, -1 indicates this pool is unlimited.
 func (p *PoolWithFunc) Free() int {
 	c := p.Cap()
 	if c < 0 {