From patchwork Fri May 10 12:16:35 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 242966 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 7DA532C00A0 for ; Fri, 10 May 2013 22:17:27 +1000 (EST) Received: from localhost ([::1]:52342 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UamGL-0003kU-Ic for incoming@patchwork.ozlabs.org; Fri, 10 May 2013 08:17:25 -0400 Received: from eggs.gnu.org ([208.118.235.92]:39902) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UamFo-0003hN-VQ for qemu-devel@nongnu.org; Fri, 10 May 2013 08:16:54 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UamFn-0007ik-Ic for qemu-devel@nongnu.org; Fri, 10 May 2013 08:16:52 -0400 Received: from mail-we0-x236.google.com ([2a00:1450:400c:c03::236]:64802) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UamFn-0007id-DG for qemu-devel@nongnu.org; Fri, 10 May 2013 08:16:51 -0400 Received: by mail-we0-f182.google.com with SMTP id t60so3928414wes.41 for ; Fri, 10 May 2013 05:16:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=x-received:sender:from:to:cc:subject:date:message-id:x-mailer :in-reply-to:references; bh=rKzj5nN4WYMlQbMp+o1QJiC6O4NNPhrSHYg+MW0dfFc=; b=oEBJnYaNRrG0ThIyHODDRT35+ibUk6RRcf5agUObEaQFg66H7jzp6ErmzSGVDgDxKn 3ZJBlUnvDz+VnWwlATlYQUc7XpthL83jJybXG24UP4MS///Os7nxp/Vm7y7+VoAaScRN EZxdhpN+I+cqxRstL2IHxbbgGJhZTSOyXRrkkY732WdzSHsM6c0yLFonfbNL1tdAXLW4 vk/GkWzc4Gmo5jS815709VWEhnDf9kYd7rMVSO9UkffRRvGx3bfdSTW0cGjeoVOt7ON0 EvHOp390tY3rwpDod0xk1+YGJyL+/+UQAKrUFuoYUiIL25X5DBuBLQBM8H0M4qEnFayr C+Dw== X-Received: by 10.195.13.75 with SMTP id ew11mr24370205wjd.25.1368188210745; Fri, 10 May 2013 05:16:50 -0700 (PDT) Received: from playground.lan (93-34-176-20.ip50.fastwebnet.it. [93.34.176.20]) by mx.google.com with ESMTPSA id er17sm3529771wic.0.2013.05.10.05.16.48 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Fri, 10 May 2013 05:16:49 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Date: Fri, 10 May 2013 14:16:35 +0200 Message-Id: <1368188203-3407-2-git-send-email-pbonzini@redhat.com> X-Mailer: git-send-email 1.8.1.4 In-Reply-To: <1368188203-3407-1-git-send-email-pbonzini@redhat.com> References: <1368188203-3407-1-git-send-email-pbonzini@redhat.com> X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:400c:c03::236 Cc: Anthony Liguori , Andreas Faerber , Aurelien Jarno , mst@redhat.com Subject: [Qemu-devel] [PATCH for-1.5 1/9] qom: improve documentation of cast functions X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Signed-off-by: Paolo Bonzini --- include/qom/object.h | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index d0f99c5..41b7068 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -612,7 +612,8 @@ Object *object_dynamic_cast(Object *obj, const char *typename); * * See object_dynamic_cast() for a description of the parameters of this * function. The only difference in behavior is that this function asserts - * instead of returning #NULL on failure. + * instead of returning #NULL on failure. This function is not meant to be + * called directly, but only through the wrapper macro OBJECT_CHECK. */ Object *object_dynamic_cast_assert(Object *obj, const char *typename); @@ -659,11 +660,29 @@ Type type_register(const TypeInfo *info); * @klass: The #ObjectClass to attempt to cast. * @typename: The QOM typename of the class to cast to. * - * Returns: This function always returns @klass and asserts on failure. + * See object_class_dynamic_cast() for a description of the parameters + * of this function. The only difference in behavior is that this function + * asserts instead of returning #NULL on failure. This function is not + * meant to be called directly, but only through the wrapper macros + * OBJECT_CLASS_CHECK and INTERFACE_CHECK. */ ObjectClass *object_class_dynamic_cast_assert(ObjectClass *klass, const char *typename); +/** + * object_class_dynamic_cast: + * @klass: The #ObjectClass to attempt to cast. + * @typename: The QOM typename of the class to cast to. + * + * Returns: If @typename is a class, this function returns @klass if + * @typename is a subtype of @klass, else returns #NULL. + * + * If @typename is an interface, this function returns the interface + * definition for @klass if @klass implements it unambiguously; #NULL + * is returned if @klass does not implement the interface or if multiple + * classes or interfaces on the hierarchy leading to @klass implement + * it. (FIXME: perhaps this can be detected at type definition time?) + */ ObjectClass *object_class_dynamic_cast(ObjectClass *klass, const char *typename);