File: Mnesia_App_B.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (209 lines) | stat: -rw-r--r-- 6,818 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>Appendix B: The Backup Call Back Interface
</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="9"><!-- Empty --></A>
<H2>9 Appendix B: The Backup Call Back Interface
</H2>
<A NAME="9.1"><!-- Empty --></A>
<H3>9.1 mnesia_backup callback behavior</H3>

<P>
<PRE>

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% This module contains one implementation of callback functions
%% used by Mnesia at backup and restore. The user may however
%% write an own module the same interface as mnesia_backup and
%% configure Mnesia so the alternate module performs the actual
%% accesses to the backup media. This means that the user may put
%% the backup on medias that Mnesia does not know about, possibly
%% on hosts where Erlang is not running.
%%
%% The OpaqueData argument is never interpreted by other parts of
%% Mnesia. It is the property of this module. Alternate implementations
%% of this module may have different interpretations of OpaqueData.
%% The OpaqueData argument given to open_write/1 and open_read/1
%% are forwarded directly from the user.
%%
%% All functions must return {ok, NewOpaqueData} or {error, Reason}.
%%
%% The NewOpaqueData arguments returned by backup callback functions will
%% be given as input when the next backup callback function is invoked.
%% If any return value does not match {ok, _} the backup will be aborted.
%%
%% The NewOpaqueData arguments returned by restore callback functions will
%% be given as input when the next restore callback function is invoked
%% If any return value does not match {ok, _} the restore will be aborted.
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

-module(mnesia_backup).

-include_lib(&#34;kernel/include/file.hrl&#34;).

-export([
         %% Write access
         open_write/1, 
         write/2, 
         commit_write/1, 
         abort_write/1,

         %% Read access
         open_read/1, 
         read/1, 
         close_read/1
        ]).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Backup callback interface
-record(backup, {tmp_file, file, file_desc}).

%% Opens backup media for write
%%
%% Returns {ok, OpaqueData} or {error, Reason}
open_write(OpaqueData) -&#62;
    File = OpaqueData,
    Tmp = lists:concat([File,&#34;.BUPTMP&#34;]),
    file:delete(Tmp),
    file:delete(File),
    case disk_log:open([{name, make_ref()},
                        {file, Tmp},
                        {repair, false},
                        {linkto, self()}]) of
        {ok, Fd} -&#62;
            {ok, #backup{tmp_file = Tmp, file = File, file_desc = Fd}};
        {error, Reason} -&#62;
            {error, Reason}
    end.

%% Writes BackupItems to the backup media
%%
%% Returns {ok, OpaqueData} or {error, Reason}
write(OpaqueData, BackupItems) -&#62;
    B = OpaqueData,
    case disk_log:log_terms(B#backup.file_desc, BackupItems) of
        ok -&#62;
            {ok, B};
        {error, Reason} -&#62;
            abort_write(B),
            {error, Reason}
    end.

%% Closes the backup media after a successful backup
%%
%% Returns {ok, ReturnValueToUser} or {error, Reason}
commit_write(OpaqueData) -&#62;
    B = OpaqueData,
    case disk_log:sync(B#backup.file_desc) of
        ok -&#62;
            case disk_log:close(B#backup.file_desc) of
                ok -&#62;
                    case file:rename(B#backup.tmp_file, B#backup.file) of
                       ok -&#62;
                            {ok, B#backup.file};
                       {error, Reason} -&#62;
                            {error, Reason}
                    end;
                {error, Reason} -&#62;
                    {error, Reason}
            end;
        {error, Reason} -&#62;
            {error, Reason}
    end.

%% Closes the backup media after an interrupted backup
%%
%% Returns {ok, ReturnValueToUser} or {error, Reason}
abort_write(BackupRef) -&#62;
    Res = disk_log:close(BackupRef#backup.file_desc),
    file:delete(BackupRef#backup.tmp_file),
    case Res of
        ok -&#62;
            {ok, BackupRef#backup.file};
        {error, Reason} -&#62;
            {error, Reason}
    end.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Restore callback interface

-record(restore, {file, file_desc, cont}).

%% Opens backup media for read
%%
%% Returns {ok, OpaqueData} or {error, Reason}
open_read(OpaqueData) -&#62;
    File = OpaqueData,
    case file:read_file_info(File) of
        {error, Reason} -&#62;
            {error, Reason};
        _FileInfo -&#62; %% file exists
            case disk_log:open([{file, File},
                                {name, make_ref()},
                                {repair, false},
                                {mode, read_only},
                                {linkto, self()}]) of
                {ok, Fd} -&#62;
                    {ok, #restore{file = File, file_desc = Fd, cont = start}};
                {repaired, Fd, _, {badbytes, 0}} -&#62;
                    {ok, #restore{file = File, file_desc = Fd, cont = start}};
                {repaired, Fd, _, _} -&#62;
                    {ok, #restore{file = File, file_desc = Fd, cont = start}};
                {error, Reason} -&#62;
                    {error, Reason}
            end
    end.

%% Reads BackupItems from the backup media
%%
%% Returns {ok, OpaqueData, BackupItems} or {error, Reason}
%%
%% BackupItems == [] is interpreted as eof
read(OpaqueData) -&#62;
    R = OpaqueData,
    Fd = R#restore.file_desc,
    case disk_log:chunk(Fd, R#restore.cont) of
        {error, Reason} -&#62;
            {error, {&#34;Possibly truncated&#34;, Reason}};
        eof -&#62;
            {ok, R, []};
        {Cont, []} -&#62;
            read(R#restore{cont = Cont});
        {Cont, BackupItems, _BadBytes} -&#62;
            {ok, R#restore{cont = Cont}, BackupItems};
        {Cont, BackupItems} -&#62;
            {ok, R#restore{cont = Cont}, BackupItems}
    end.

%% Closes the backup media after restore
%%
%% Returns {ok, ReturnValueToUser} or {error, Reason}
close_read(OpaqueData) -&#62;
    R = OpaqueData,
    case disk_log:close(R#restore.file_desc) of
        ok -&#62; {ok, R#restore.file};
        {error, Reason} -&#62; {error, Reason}
    end.

</PRE>
<CENTER>
<HR>
<SMALL>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>