update godoc
Vladimir Bauer
2 years ago
| 17 | 17 | defaultRefreshRate = 150 * time.Millisecond |
| 18 | 18 | ) |
| 19 | 19 | |
| 20 | // DoneError represents an error when `*mpb.Progress` is done but its functionality is requested. | |
| 21 | var DoneError = fmt.Errorf("%T instance can't be reused after it's done", (*Progress)(nil)) | |
| 20 | // DoneError represents use after `(*Progress).Wait()` error. | |
| 21 | var DoneError = fmt.Errorf("%T instance can't be reused after %[1]T.Wait()", (*Progress)(nil)) | |
| 22 | 22 | |
| 23 | 23 | // Progress represents a container that renders one or more progress bars. |
| 24 | 24 | type Progress struct { |
| 54 | 54 | } |
| 55 | 55 | |
| 56 | 56 | // New creates new Progress container instance. It's not possible to |
| 57 | // reuse instance after (*Progress).Wait method has been called. | |
| 57 | // reuse instance after `(*Progress).Wait` method has been called. | |
| 58 | 58 | func New(options ...ContainerOption) *Progress { |
| 59 | 59 | return NewWithContext(context.Background(), options...) |
| 60 | 60 | } |
| 61 | 61 | |
| 62 | 62 | // NewWithContext creates new Progress container instance with provided |
| 63 | // context. It's not possible to reuse instance after (*Progress).Wait | |
| 63 | // context. It's not possible to reuse instance after `(*Progress).Wait` | |
| 64 | 64 | // method has been called. |
| 65 | 65 | func NewWithContext(ctx context.Context, options ...ContainerOption) *Progress { |
| 66 | 66 | if ctx == nil { |
| 132 | 132 | |
| 133 | 133 | // MustAdd creates a bar which renders itself by provided BarFiller. |
| 134 | 134 | // If `total <= 0` triggering complete event by increment methods is |
| 135 | // disabled. Panics if *Progress instance is done, i.e. called after | |
| 136 | // (*Progress).Wait(). | |
| 135 | // disabled. Panics if called after `(*Progress).Wait()`. | |
| 137 | 136 | func (p *Progress) MustAdd(total int64, filler BarFiller, options ...BarOption) *Bar { |
| 138 | 137 | bar, err := p.Add(total, filler, options...) |
| 139 | 138 | if err != nil { |
| 144 | 143 | |
| 145 | 144 | // Add creates a bar which renders itself by provided BarFiller. |
| 146 | 145 | // If `total <= 0` triggering complete event by increment methods |
| 147 | // is disabled. If *Progress instance is done, i.e. called after | |
| 148 | // (*Progress).Wait(), return error == DoneError. | |
| 146 | // is disabled. If called after `(*Progress).Wait()` then | |
| 147 | // `(nil, DoneError)` is returned. | |
| 149 | 148 | func (p *Progress) Add(total int64, filler BarFiller, options ...BarOption) (*Bar, error) { |
| 150 | 149 | if filler == nil { |
| 151 | 150 | filler = NopStyle().Build() |
| 202 | 201 | |
| 203 | 202 | // UpdateBarPriority either immediately or lazy. |
| 204 | 203 | // With lazy flag order is updated after the next refresh cycle. |
| 205 | // If you don't care about laziness just use *Bar.SetPriority(int). | |
| 204 | // If you don't care about laziness just use `(*Bar).SetPriority(int)`. | |
| 206 | 205 | func (p *Progress) UpdateBarPriority(b *Bar, priority int, lazy bool) { |
| 207 | 206 | if b == nil { |
| 208 | 207 | return |
| 214 | 213 | } |
| 215 | 214 | |
| 216 | 215 | // Write is implementation of io.Writer. |
| 217 | // Writing to `*mpb.Progress` will print lines above a running bar. | |
| 216 | // Writing to `*Progress` will print lines above a running bar. | |
| 218 | 217 | // Writes aren't flushed immediately, but at next refresh cycle. |
| 219 | // If Write is called after `*mpb.Progress` is done, `mpb.DoneError` | |
| 218 | // If called after `(*Progress).Wait()` then `(0, DoneError)` | |
| 220 | 219 | // is returned. |
| 221 | 220 | func (p *Progress) Write(b []byte) (int, error) { |
| 222 | 221 | type result struct { |
| 237 | 236 | } |
| 238 | 237 | |
| 239 | 238 | // Wait waits for all bars to complete and finally shutdowns container. After |
| 240 | // this method has been called, there is no way to reuse (*Progress) instance. | |
| 239 | // this method has been called, there is no way to reuse `*Progress` instance. | |
| 241 | 240 | func (p *Progress) Wait() { |
| 242 | 241 | // wait for user wg, if any |
| 243 | 242 | if p.uwg != nil { |
| 248 | 247 | p.Shutdown() |
| 249 | 248 | } |
| 250 | 249 | |
| 251 | // Shutdown cancels any running bar immediately and then shutdowns (*Progress) | |
| 250 | // Shutdown cancels any running bar immediately and then shutdowns `*Progress` | |
| 252 | 251 | // instance. Normally this method shouldn't be called unless you know what you |
| 253 | // are doing. Proper way to shutdown is to call (*Progress).Wait() instead. | |
| 252 | // are doing. Proper way to shutdown is to call `(*Progress).Wait()` instead. | |
| 254 | 253 | func (p *Progress) Shutdown() { |
| 255 | 254 | p.cancel() |
| 256 | 255 | p.pwg.Wait() |