github.com/vmware/govmomi@v0.37.1/object/task.go (about)

     1  /*
     2  Copyright (c) 2015-2024 VMware, Inc. All Rights Reserved.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8  http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  package object
    18  
    19  import (
    20  	"context"
    21  	"fmt"
    22  
    23  	"github.com/vmware/govmomi/property"
    24  	"github.com/vmware/govmomi/task"
    25  	"github.com/vmware/govmomi/vim25"
    26  	"github.com/vmware/govmomi/vim25/methods"
    27  	"github.com/vmware/govmomi/vim25/progress"
    28  	"github.com/vmware/govmomi/vim25/types"
    29  )
    30  
    31  // Task is a convenience wrapper around task.Task that keeps a reference to
    32  // the client that was used to create it. This allows users to call the Wait()
    33  // function with only a context parameter, instead of a context parameter, a
    34  // soap.RoundTripper, and reference to the root property collector.
    35  type Task struct {
    36  	Common
    37  }
    38  
    39  func NewTask(c *vim25.Client, ref types.ManagedObjectReference) *Task {
    40  	t := Task{
    41  		Common: NewCommon(c, ref),
    42  	}
    43  
    44  	return &t
    45  }
    46  
    47  // Wait waits for a task to complete.
    48  // NOTE: This method create a thread-safe PropertyCollector instance per-call, so it is thread safe.
    49  // The downside of this approach is the additional resource usage on the vCenter side for each call.
    50  func (t *Task) Wait(ctx context.Context) error {
    51  	_, err := t.WaitForResult(ctx, nil)
    52  	return err
    53  }
    54  
    55  // WaitForResult wait for a task to complete.
    56  // NOTE: This method create a thread-safe PropertyCollector instance per-call, so it is thread safe.
    57  // The downside of this approach is the additional resource usage on the vCenter side for each call.
    58  func (t *Task) WaitForResult(ctx context.Context, s ...progress.Sinker) (taskInfo *types.TaskInfo, result error) {
    59  	var pr progress.Sinker
    60  	if len(s) == 1 {
    61  		pr = s[0]
    62  	}
    63  	p, err := property.DefaultCollector(t.c).Create(ctx)
    64  	if err != nil {
    65  		return nil, err
    66  	}
    67  
    68  	// Attempt to destroy the collector using the background context, as the
    69  	// specified context may have timed out or have been canceled.
    70  	defer func() {
    71  		if err := p.Destroy(context.Background()); err != nil {
    72  			if result == nil {
    73  				result = err
    74  			} else {
    75  				result = fmt.Errorf(
    76  					"destroy property collector failed with %s after failing to wait for updates: %w",
    77  					err,
    78  					result)
    79  			}
    80  		}
    81  	}()
    82  
    83  	return task.WaitEx(ctx, t.Reference(), p, pr)
    84  }
    85  
    86  // WaitEx waits for a task to complete.
    87  // NOTE: This method use the same PropertyCollector instance in each call, thus reducing resource usage on the vCenter side.
    88  // The downside of this approach is that this method is not thread safe.
    89  func (t *Task) WaitEx(ctx context.Context) error {
    90  	_, err := t.WaitForResultEx(ctx, nil)
    91  	return err
    92  }
    93  
    94  // WaitForResultEx waits for a task to complete.
    95  // NOTE: This method use the same PropertyCollector instance in each call, thus reducing resource usage on the vCenter side.
    96  // The downside of this approach is that this method is not thread safe.
    97  func (t *Task) WaitForResultEx(ctx context.Context, s ...progress.Sinker) (*types.TaskInfo, error) {
    98  	var pr progress.Sinker
    99  	if len(s) == 1 {
   100  		pr = s[0]
   101  	}
   102  	p := property.DefaultCollector(t.c)
   103  	return task.WaitEx(ctx, t.Reference(), p, pr)
   104  }
   105  
   106  func (t *Task) Cancel(ctx context.Context) error {
   107  	_, err := methods.CancelTask(ctx, t.Client(), &types.CancelTask{
   108  		This: t.Reference(),
   109  	})
   110  
   111  	return err
   112  }
   113  
   114  // SetState sets task state and optionally sets results or fault, as appropriate for state.
   115  func (t *Task) SetState(ctx context.Context, state types.TaskInfoState, result types.AnyType, fault *types.LocalizedMethodFault) error {
   116  	req := types.SetTaskState{
   117  		This:   t.Reference(),
   118  		State:  state,
   119  		Result: result,
   120  		Fault:  fault,
   121  	}
   122  	_, err := methods.SetTaskState(ctx, t.Common.Client(), &req)
   123  	return err
   124  }
   125  
   126  // SetDescription updates task description to describe the current phase of the task.
   127  func (t *Task) SetDescription(ctx context.Context, description types.LocalizableMessage) error {
   128  	req := types.SetTaskDescription{
   129  		This:        t.Reference(),
   130  		Description: description,
   131  	}
   132  	_, err := methods.SetTaskDescription(ctx, t.Common.Client(), &req)
   133  	return err
   134  }
   135  
   136  // UpdateProgress Sets percentage done for this task and recalculates overall percentage done.
   137  // If a percentDone value of less than zero or greater than 100 is specified,
   138  // a value of zero or 100 respectively is used.
   139  func (t *Task) UpdateProgress(ctx context.Context, percentDone int) error {
   140  	req := types.UpdateProgress{
   141  		This:        t.Reference(),
   142  		PercentDone: int32(percentDone),
   143  	}
   144  	_, err := methods.UpdateProgress(ctx, t.Common.Client(), &req)
   145  	return err
   146  }