# -*- Mode: Python -*-
# vim: filetype=python
#

##
# = Yank feature
##

##
# @YankInstanceType:
#
# An enumeration of yank instance types. See @YankInstance for more
# information.
#
# Since: 6.0
##
{ 'enum': 'YankInstanceType',
  'data': [ 'block-node', 'chardev', 'migration' ] }

##
# @YankInstanceBlockNode:
#
# Specifies which block graph node to yank. See @YankInstance for more
# information.
#
# @node-name: the name of the block graph node
#
# Since: 6.0
##
{ 'struct': 'YankInstanceBlockNode',
  'data': { 'node-name': 'str' } }

##
# @YankInstanceChardev:
#
# Specifies which character device to yank. See @YankInstance for more
# information.
#
# @id: the chardev's ID
#
# Since: 6.0
##
{ 'struct': 'YankInstanceChardev',
  'data': { 'id': 'str' } }

##
# @YankInstance:
#
# A yank instance can be yanked with the @yank qmp command to recover from a
# hanging QEMU.
#
# Currently implemented yank instances:
#
# - nbd block device:
#   Yanking it will shut down the connection to the nbd server without
#   attempting to reconnect.
# - socket chardev:
#   Yanking it will shut down the connected socket.
# - migration:
#   Yanking it will shut down all migration connections. Unlike
#   @migrate_cancel, it will not notify the migration process, so migration
#   will go into @failed state, instead of @cancelled state. @yank should be
#   used to recover from hangs.
#
# Since: 6.0
##
{ 'union': 'YankInstance',
  'base': { 'type': 'YankInstanceType' },
  'discriminator': 'type',
  'data': {
      'block-node': 'YankInstanceBlockNode',
      'chardev': 'YankInstanceChardev' } }

##
# @yank:
#
# Try to recover from hanging QEMU by yanking the specified instances. See
# @YankInstance for more information.
#
# Takes a list of @YankInstance as argument.
#
# Returns: - Nothing on success
#          - @DeviceNotFound error, if any of the YankInstances doesn't exist
#
# Example:
#
# -> { "execute": "yank",
#      "arguments": {
#          "instances": [
#               { "type": "block-node",
#                 "node-name": "nbd0" }
#          ] } }
# <- { "return": {} }
#
# Since: 6.0
##
{ 'command': 'yank',
  'data': { 'instances': ['YankInstance'] },
  'allow-oob': true }

##
# @query-yank:
#
# Query yank instances. See @YankInstance for more information.
#
# Returns: list of @YankInstance
#
# Example:
#
# -> { "execute": "query-yank" }
# <- { "return": [
#          { "type": "block-node",
#            "node-name": "nbd0" }
#      ] }
#
# Since: 6.0
##
{ 'command': 'query-yank',
  'returns': ['YankInstance'],
  'allow-oob': true }