45
3.1 General Programming 47
>Enable warning logging in the development phase, and carefully study any warning
messages in the log file. They may point to potential problems in your code or data,
and you should try to understand or eliminate the reason for those warnings.
>Disable warning logging in the production phase, and re-enable it only in case of
problems.
3.1.2 The PDFlib Virtual File System (PVF)
Cookbook A full code sample can be found in the Cookbook topic general/starter_pvf.
In addition to disk files a facility called PDFlib Virtual File System (PVF) allows clients to di-
rectly supply data in memory without any disk files involved. This offers performance
benefits and can be used for data fetched from a database which does not even exist on
an isolated disk file, as well as other situations where the client already has the required
data available in memory as a result of some processing.
PVF is based on the concept of named virtual read-only files which can be used just
like regular file names with any API function. They can even be used in UPR configura-
tion files. Virtual file names can be generated in an arbitrary way by the client. Obvious-
ly, virtual file names must be chosen such that name clashes with regular disk files are
avoided. For this reason a hierarchical naming convention for virtual file names is rec-
ommended as follows (filename refers to a name chosen by the client which is unique in
the respective category). It is also recommended to keep standard file name suffixes:
>Raster image files: /pvf/image/filename
>font outline and metrics files (it is recommended to use the actual font name as the
base portion of the file name): /pvf/font/filename
>ICC profiles: /pvf/iccprofile/filename
>Encodings and codepages: /pvf/codepage/filename
>PDF documents: /pvf/pdf/filename
When searching for a named file PDFlib will first check whether the supplied file name
refers to a known virtual file, and then try to open the named file on disk.
Lifetime of virtual files. Some functions will immediately consume the data supplied
in a virtual file, while others will read only parts of the file, with other fragments being
used at a later point in time. For this reason close attention must be paid to the lifetime
of virtual files. PDFlib will place an internal lock on every virtual file, and remove the
lock only when the contents are no longer needed. Unless the client requested PDFlib to
make an immediate copy of the data (using the copy option in create_pvf( )), the virtual
file’s contents must only be modified, deleted, or freed by the client when it is no longer
locked by PDFlib. PDFlib will automatically delete all virtual files in delete( ). However,
the actual file contents (the data comprising a virtual file) must always be freed by the
client.
Different strategies. PVF supports different approaches with respect to managing the
memory required for virtual files. These are governed by the fact that PDFlib may need
access to a virtual file’s contents after the API call which accepted the virtual file name,
but never needs access to the contents after close( ). Remember that calling delete_pvf( )
does not free the actual file contents (unless the copy option has been supplied), but
only the corresponding data structures used for PVF file name administration. This
gives rise to the following strategies:
