[Remarks] Simplify and refactor the RemarkParser interface

Before, everything was based on some kind of type erased parser
implementation which container a lot of boilerplate code when multiple
formats were to be supported.

This simplifies it by:

* the remark now owns its arguments
* *always* returning an error from the implementation side
* working around the way the YAML parser reports errors: catch them through
callbacks and re-insert them in a proper llvm::Error
* add a CParser wrapper that is used when implementing the C API to
avoid cluttering the C++ API with useless state
* LLVMRemarkParserGetNext now returns an object that needs to be
released to avoid leaking resources
* add a new API to dispose of a remark entry: LLVMRemarkEntryDispose

llvm-svn: 366217

1 files changed, 19 insertions, 4 deletions

diff --git a/llvm/include/llvm-c/Remarks.h b/llvm/include/llvm-c/Remarks.h
index 7fb16656a9a..88eb5120c57 100644
--- a/llvm/include/llvm-c/Remarks.h
+++ b/llvm/include/llvm-c/Remarks.h
@@ -137,6 +137,13 @@ extern LLVMRemarkDebugLocRef LLVMRemarkArgGetDebugLoc(LLVMRemarkArgRef Arg);
 typedef struct LLVMRemarkOpaqueEntry *LLVMRemarkEntryRef;
 
 /**
+ * Free the resources used by the remark entry.
+ *
+ * \since REMARKS_API_VERSION=0
+ */
+extern void LLVMRemarkEntryDispose(LLVMRemarkEntryRef Remark);
+
+/**
  * The type of the remark. For example, it can allow users to only keep the
  * missed optimizations from the compiler.
  *
@@ -161,7 +168,7 @@ extern LLVMRemarkStringRef
 LLVMRemarkEntryGetRemarkName(LLVMRemarkEntryRef Remark);
 
 /**
- * Get the name of the function being processsed when the remark was emitted.
+ * Get the name of the function being processed when the remark was emitted.
  *
  * \since REMARKS_API_VERSION=0
  */
@@ -199,6 +206,8 @@ extern uint32_t LLVMRemarkEntryGetNumArgs(LLVMRemarkEntryRef Remark);
  *
  * If there are no arguments in \p Remark, the return value will be `NULL`.
  *
+ * The lifetime of the returned value is bound to the lifetime of \p Remark.
+ *
  * \since REMARKS_API_VERSION=0
  */
 extern LLVMRemarkArgRef LLVMRemarkEntryGetFirstArg(LLVMRemarkEntryRef Remark);
@@ -208,6 +217,8 @@ extern LLVMRemarkArgRef LLVMRemarkEntryGetFirstArg(LLVMRemarkEntryRef Remark);
  *
  * Returns `NULL` if there are no more arguments available.
  *
+ * The lifetime of the returned value is bound to the lifetime of \p Remark.
+ *
  * \since REMARKS_API_VERSION=0
  */
 extern LLVMRemarkArgRef LLVMRemarkEntryGetNextArg(LLVMRemarkArgRef It,
@@ -232,8 +243,11 @@ extern LLVMRemarkParserRef LLVMRemarkParserCreateYAML(const void *Buf,
 /**
  * Returns the next remark in the file.
  *
- * The value pointed to by the return value is invalidated by the next call to
- * LLVMRemarkParserGetNext().
+ * The value pointed to by the return value needs to be disposed using a call to
+ * LLVMRemarkEntryDispose().
+ *
+ * All the entries in the returned value that are of LLVMRemarkStringRef type
+ * will become invalidated once a call to LLVMRemarkParserDispose is made.
  *
  * If the parser reaches the end of the buffer, the return value will be `NULL`.
  *
@@ -258,8 +272,9 @@ extern LLVMRemarkParserRef LLVMRemarkParserCreateYAML(const void *Buf,
  * ```
  * LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
  * LLVMRemarkEntryRef Remark = NULL;
- * while ((Remark == LLVMRemarkParserGetNext(Parser))) {
+ * while ((Remark = LLVMRemarkParserGetNext(Parser))) {
  *    // use Remark
+ *    LLVMRemarkEntryDispose(Remark); // Release memory.
  * }
  * bool HasError = LLVMRemarkParserHasError(Parser);
  * LLVMRemarkParserDispose(Parser);