/*

 * Copyright (c) 2020 Red Hat, Inc.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 * 

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 * 

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA

 * 02110-1301, USA. 

 *

 * $Id: //eng/vdo-releases/aluminum/src/c++/vdo/base/adminCompletion.h#4 $

 */

#ifndef ADMIN_COMPLETION_H

#define ADMIN_COMPLETION_H

#include "atomic.h"

#include "completion.h"

#include "types.h"

typedef enum adminOperationType {

  ADMIN_OPERATION_UNKNOWN = 0,

  ADMIN_OPERATION_GROW_LOGICAL,

  ADMIN_OPERATION_GROW_PHYSICAL,

  ADMIN_OPERATION_PREPARE_GROW_PHYSICAL,

  ADMIN_OPERATION_LOAD,

  ADMIN_OPERATION_RESUME,

  ADMIN_OPERATION_SAVE,

  ADMIN_OPERATION_SUSPEND,

} AdminOperationType;

typedef struct adminCompletion AdminCompletion;

/**

 * A function which gets the ID of the thread on which the current phase of an

 * admin operation should be run.

 *

 * @param adminCompletion The AdminCompletion

 *

 * @return The ID of the thread on which the current phase should be performed

 **/

typedef ThreadID ThreadIDGetterForPhase(AdminCompletion *adminCompletion);

struct adminCompletion {

  /** The completion */

  VDOCompletion           completion;

  /** The sub-task completion */

  VDOCompletion           subTaskCompletion;

  /** Whether this completion is in use */

  AtomicBool              busy;

  /** The operation type */

  AdminOperationType      type;

  /** Method to get the ThreadID for the current phase */

  ThreadIDGetterForPhase *getThreadID;

  /** The current phase of the operation */

  uint32_t                phase;

};

/**

 * Check that an AdminCompletion's type is as expected.

 *

 * @param completion  The AdminCompletion to check

 * @param expected    The expected type

 **/

void assertAdminOperationType(AdminCompletion    *completion,

                              AdminOperationType  expected);

/**

 * Convert the sub-task completion of an AdminCompletion to an AdminCompletion.

 *

 * @param completion  the AdminCompletion's sub-task completion

 *

 * @return The sub-task completion as its enclosing AdminCompletion

 **/

AdminCompletion *adminCompletionFromSubTask(VDOCompletion *completion)

  __attribute__((warn_unused_result));

/**

 * Assert that we are operating on the correct thread for the current phase.

 *

 * @param adminCompletion  The AdminCompletion to check

 * @param what             The method doing the phase check

 * @param phaseNames       The names of the phases of the current operation

 **/

void assertAdminPhaseThread(AdminCompletion *adminCompletion,

                            const char      *what,

                            const char      *phaseNames[]);

/**

 * Get the VDO from the sub-task completion of its AdminCompletion.

 *

 * @param completion  the sub-task completion

 * @param expected    the expected operation type of the AdminCompletion

 *

 * @return The VDO

 **/

VDO *vdoFromAdminSubTask(VDOCompletion      *completion,

                         AdminOperationType  expected)

  __attribute__((warn_unused_result));

/**

 * Initialize an admin completion.

 *

 * @param vdo               The VDO which owns the completion

 * @param adminCompletion   The AdminCompletion to initialize

 *

 * @return VDO_SUCCESS or an error

 **/

int initializeAdminCompletion(VDO *vdo, AdminCompletion *adminCompletion)

  __attribute__((warn_unused_result));

/**

 * Clean up an admin completion's resources.

 *

 * @param adminCompletion  The AdminCompletion to uninitialize

 **/

void uninitializeAdminCompletion(AdminCompletion *adminCompletion);

/**

 * Reset an AdminCompletion's sub-task completion.

 *

 * @param completion  The AdminCompletion's sub-task completion

 *

 * @return The sub-task completion for the convenience of callers

 **/

VDOCompletion *resetAdminSubTask(VDOCompletion *completion);

/**

 * Prepare the sub-task completion of a VDO's AdminCompletion

 *

 * @param vdo           The VDO

 * @param callback      The callback for the sub-task

 * @param errorHandler  The error handler for the sub-task

 * @param threadID      The ID of the thread on which to run the callback

 **/

void prepareAdminSubTaskOnThread(VDO       *vdo,

                                 VDOAction *callback,

                                 VDOAction *errorHandler,

                                 ThreadID   threadID);

/**

 * Prepare the sub-task completion of a VDO's AdminCompletion to run on the

 * same thread as the AdminCompletion's main completion.

 *

 * @param vdo           The VDO

 * @param callback      The callback for the sub-task

 * @param errorHandler  The error handler for the sub-task

 **/

void prepareAdminSubTask(VDO       *vdo,

                         VDOAction *callback,

                         VDOAction *errorHandler);

/**

 * Perform an administrative operation (load, suspend, grow logical, or grow

 * physical). This method should not be called from base threads unless it is

 * certain the calling thread won't be needed to perform the operation. It may

 * (and should) be called from non-base threads.

 *

 * @param vdo             The VDO on which to perform the operation

 * @param type            The type of operation to perform

 * @param threadIDGetter  A function for getting the ID of the thread on which

 *                        a given phase should be run

 * @param action          The action which starts the operation

 * @param errorHandler    The error handler for the operation

 *

 * @return The result of the operation

 **/

int performAdminOperation(VDO                    *vdo,

                          AdminOperationType      type,

                          ThreadIDGetterForPhase *threadIDGetter,

                          VDOAction              *action,

                          VDOAction              *errorHandler)

  __attribute__((warn_unused_result));

#endif /* ADMIN_COMPLETION_H */