Add 'pdf_pin_document' API to future proof us.

In the next version, we plan to rewrite the internal
pdf_obj -> pdf_doc reference handling to use a "weak
reference" system. This will protect us more against
the document being dropped while references are still
held to pdf_objs.

The largest potential for this is with systems which
wrap MuPDF's C API into garbage collected objects
(such as Java and Python).

Accordingly, people should move their code to use
pdf_pin_document instead of pdf_get_bound_document
and pdf_get_indirect_document.

diff --git a/include/mupdf/pdf/object.h b/include/mupdf/pdf/object.h
index 5ce00ff86dfa33d13b7b4be18d0166e42c4abd3b..94c63251be1127c05b90424206e496474f7d3109 100644 (file)
--- a/include/mupdf/pdf/object.h
+++ b/include/mupdf/pdf/object.h
@@ -272,8 +272,39 @@ fz_rect pdf_to_rect(fz_context *ctx, pdf_obj *array);
 fz_matrix pdf_to_matrix(fz_context *ctx, pdf_obj *array);
 int64_t pdf_to_date(fz_context *ctx, pdf_obj *time);
 
+/*
+       pdf_get_indirect_document and pdf_get_bound_document are
+       now deprecated. Please do not use them in future. They will
+       be removed.
+
+       Please use pdf_pin_document instead.
+*/
 pdf_document *pdf_get_indirect_document(fz_context *ctx, pdf_obj *obj);
 pdf_document *pdf_get_bound_document(fz_context *ctx, pdf_obj *obj);
+
+/*
+       pdf_pin_document returns a new reference to the document
+       to which obj is bound. The caller is responsible for
+       dropping this reference once they have finished with it.
+
+       This is a replacement for pdf_get_indirect_document
+       and pdf_get_bound_document that are now deprecated. Those
+       returned a borrowed reference that did not need to be
+       dropped.
+
+       Note that this can validly return NULL in various cases:
+       1) When the object is of a simple type (such as a number
+       or a string), it contains no reference to the enclosing
+       document. 2) When the object has yet to be inserted into
+       a PDF document (such as during parsing). 3) And (in
+       future versions) when the document has been destroyed
+       but the object reference remains.
+
+       It is the caller's responsibility to deal with a NULL
+       return here.
+*/
+pdf_document *pdf_pin_document(fz_context *ctx, pdf_obj *obj);
+
 void pdf_set_int(fz_context *ctx, pdf_obj *obj, int64_t i);
 
 /* Voodoo to create PDF_NAME(Foo) macros from name-table.h */

diff --git a/source/pdf/pdf-object.c b/source/pdf/pdf-object.c
index 39662b00db49588d553d2536b6d498853b206127..6971260aa6f73f2c8288da4ebfbfe86d0a3644ad 100644 (file)
--- a/source/pdf/pdf-object.c
+++ b/source/pdf/pdf-object.c
@@ -468,6 +468,9 @@ int pdf_to_gen(fz_context *ctx, pdf_obj *obj)
        return 0;
 }
 
+/*
+       DEPRECATED: Do not use in new code.
+*/
 pdf_document *pdf_get_indirect_document(fz_context *ctx, pdf_obj *obj)
 {
        if (OBJ_IS_INDIRECT(obj))
@@ -475,6 +478,9 @@ pdf_document *pdf_get_indirect_document(fz_context *ctx, pdf_obj *obj)
        return NULL;
 }
 
+/*
+       DEPRECATED: Do not use in new code.
+*/
 pdf_document *pdf_get_bound_document(fz_context *ctx, pdf_obj *obj)
 {
        if (obj < PDF_LIMIT)
@@ -488,6 +494,16 @@ pdf_document *pdf_get_bound_document(fz_context *ctx, pdf_obj *obj)
        return NULL;
 }
 
+/*
+       This implementation will do to provide the required
+       API change in advance of the rewrite to use weak references
+       in the next version.
+*/
+pdf_document *pdf_pin_document(fz_context *ctx, pdf_obj *obj)
+{
+       return pdf_keep_document(ctx, pdf_get_bound_document(ctx, obj));
+}
+
 int pdf_objcmp_resolve(fz_context *ctx, pdf_obj *a, pdf_obj *b)
 {
        RESOLVE(a);