[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [libvirt] RFC [1/3]: The internal lock manager API



/**
 * virLockManager:
 *
 * A lock manager is a process that will supervise another
 * process. It will obtain & hold locks/leases for resources
 * the supervised process uses
 */

typedef struct virLockManager virLockManager;
typedef virLockManager *virLockManagerPtr;

typedef enum {
    VIR_LOCK_MANAGER_RESOURCE_READONLY = (1 << 0),
    VIR_LOCK_MANAGER_RESOURCE_SHARED   = (1 << 1),
} virLockManagerResourceFlags;

enum {
    VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK = 0,
} virLockManagerResourceType;

enum {
    VIR_LOCK_MANAGER_NEW_DOMAIN = 0,
} virLockManagerNewType;

enum {
    VIR_LOCK_MANAGER_NEW_MIGRATE = (1 << 0),
    VIR_LOCK_MANAGER_NEW_ATTACH  = (1 << 1),
} virLockManagerNewFlags;

enum {
    VIR_LOCK_MANAGER_MIGRATE_CANCEL = (1 << 0);
} virLockManagerCompleteMigrateFlags;


/**
 * virLockManagerNew:
 * @driver: the driver implementation to use
 * @type: the type of process to be supervised
 * @flags: one of virLockManagerNewFlags
 *
 * Create a new context to supervise a process, usually
 * a virtual machine. For a normal startup, flags can
 * be 0. For incoming migration, use VIR_LOCK_MANAGER_NEW_MIGRATE
 *
 * Returns a new lock manager context
 */
virLockManagerPtr virLockManagerNew(virLockManagerDriverPtr driver,
                                    unsigned int type,
                                    unsigned int flags);

/**
 * virLockManagerSetParameter:
 * @manager: the lock manager context
 * @key: the parameter name
 * @value: the parameter value
 *
 * Set a configuration parameter for the managed process.
 * A process of VIR_LOCK_MANAGER_START_DOMAIN will be
 * given at least 3 parameters:
 *
 * - id: the domain unique id
 * - uuid: the domain uuid
 * - name: the domain name
 *
 * There may be other parameters specific to the lock manager
 * plugin that are provided for the managed process
 *
 * This should only be called prior to the supervised process
 * being started. Setting parameters may change the set of
 * argv returned by virLockManagerGetSupervisorArgs.
 */
int virLockManagerSetParameter(virLockManagerPtr manager,
                               const char *key,
                               const char *value);


/**
 * virLockManagerRegisterResource:
 * @manager: the lock manager context
 * @type: the resource type virLockManagerResourceType
 * @name: the resource name
 * @flags: the resource access flags
 *
 * Register a resource that is required when the process
 * starts up. This may only be called prior to the process
 * being started. The format of @name varies according to
 * the resource @type. A VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK
 * will have a fully qualified file path.
 *
 * If no flags are given, the resource is assumed to be
 * used in exclusive, read-write mode. Access can be
 * relaxed to readonly, or shared read-write.
 */
int virLockManagerRegisterResource(virLockManagerPtr manager,
                                   unsigned int type,
                                   const gchar *name,
                                   unsigned int flags);

/**
 * virLockManagerAcquireResource:
 * @manager: the lock manager context
 * @type: the resource type virLockManagerResourceType
 * @name: the resource name
 * @flags: the resource access flags
 *
 * Dynamically acquire a resource for a running process.
 * This may only be called once the process has been
 * started. The format of @name varies according to
 * the resource @type. A VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK
 * will have a fully qualified file path.
 *
 * If no flags are given, the resource is assumed to be
 * used in exclusive, read-write mode. Access can be
 * relaxed to readonly, or shared read-write.
 */
int virLockManagerAcquireResource(virLockManagerPtr manager,
                                  const gchar *file,
                                  unsigned int flags);

/**
 * virLockManagerReleaseResource:
 * @manager: the lock manager context
 * @type: the resource type virLockManagerResourceType
 * @name: the resource name
 * @flags: the resource access flags
 *
 * Dynamically release a resource for a running process.
 * This may only be called after the process has been
 * started. The format of @name varies according to
 * the resource @type. A VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK
 * will have a fully qualified file path.
 *
 * If no flags are given, the resource is assumed to be
 * used in exclusive, read-write mode. Access can be
 * relaxed to readonly, or shared read-write.
 */
int virLockManagerReleaseResource(virLockManagerPtr manager,
                                  const gchar *file,
                                  unsigned int flags);

/**
 * virLockManager:
 * @manager: the lock manager context
 *
 * Retrieve the path of the supervisor binary
 */
char *virLockManagerGetSupervisorPath(virLockManagerPtr manager);

/**
 * virLockManager:
 * @manager: the lock manager context
 * 
 * Retrieve the security context of the supervisor binary
 */
char *virLockManagerGetSupervisorContext(virLockManagerPtr manager);


/**
 * virLockManager:
 * @manager: the lock manager context
 * @argv: returned argument values
 * @argc: returned argument count
 *
 * Retrieve custom argv to pass to the supervisor binary
 * ahead of the normal process binary & argv. It is recommended
 * that the last argv be '--' to allow reliable determination
 * of the last supervisor arg.
 */
int virLockManagerGetSupervisorArgs(virLockManagerPtr manager,
                                    char ***argv,
                                    int *argc,
                                    unsigned int flags);

/**
 * virLockManagerPrepareMigrate:
 * @manager: the lock manager context
 * @targetURI: destination of the migration
 *
 * Notify the supevisor that the process is about to be migrated
 * to another host at @targetURI
 */
int virLockManagerPrepareMigrate(virLockManagerPtr manager,
                                 const char *targetURI,
                                 unsigned int flags);
/**
 * virLockManagerCompleteMigrateIn:
 * @manager: the lock manager context
 * @sourceURI: the origin of the migration
 *
 * Notify the supervisor that the process has completed
 * migration. If the migration is aborted, then the @flags
 * should be VIR_LOCK_MANAGER_MIGRATE_CANCEL
 */
int virLockManagerCompleteMigrateIn(virLockManagerPtr manager,
                                    const char *sourceURI,
                                    unsigned int flags);
/**
 * virLockManagerCompleteMigrateOut:
 * @manager: the lock manager context
 * @targetURI: the destination of the migration
 *
 * Notify the supervisor that the process has completed
 * migration. If the migration is aborted, then the @flags
 * should be VIR_LOCK_MANAGER_MIGRATE_CANCEL
 */
int virLockManagerCompleteMigrateOut(virLockManagerPtr manager,
                                     const char *targetURI,
                                     unsigned int flags);


/**
 * virLockManagerGetChild:
 * @manager: the lock manager context
 *
 * Obtain the PID of the managed process
 */
int virLockManagerGetChild(virLockManagerPtr manager,
                           pid_t *pid,
                           unsigned int flags);


/**
 * virLockManager:
 * @manager: the lock manager context
 *
 * Inform the supervisor that the supervised process has
 * been, or can be stopped.
 */
int virLockManagerShutdown(virLockManagerPtr manager,
                           unsigned int flags);

/**
 * virLockManager:
 * @manager: the lock manager context
 *
 * Release resources. If the supervised process is still
 * running, it will be killed with prejudice
 */
void virLockManagerFree(virLockManagerPtr manager);

-- 
|: Red Hat, Engineering, London    -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :|
|: http://autobuild.org        -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]