From 5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 16:01:56 +0200 Subject: Use Erlang specs and types for documentation --- lib/kernel/doc/src/disk_log.xml | 451 ++++++++++++++++++---------------------- 1 file changed, 197 insertions(+), 254 deletions(-) (limited to 'lib/kernel/doc/src/disk_log.xml') diff --git a/lib/kernel/doc/src/disk_log.xml b/lib/kernel/doc/src/disk_log.xml index 324d4264cf..9721907162 100644 --- a/lib/kernel/doc/src/disk_log.xml +++ b/lib/kernel/doc/src/disk_log.xml @@ -179,13 +179,48 @@ reopen the log simultaneously.

+ + + + + + + + + + + + + + + + + + + + + + + + +

Chunk continuation returned by + chunk/2,3, bchunk/2,3, or chunk_step/3.

+ + + + + + + + + + + + - accessible_logs() -> {[LocalLog], [DistributedLog]} + Return the accessible disk logs on the current node. - - LocalLog = DistributedLog = term() -

The accessible_logs/0 function returns the names of the disk logs accessible on the current node. @@ -195,16 +230,13 @@ - alog(Log, Term) - balog(Log, Bytes) -> ok | {error, Reason} + + + + + + Asynchronously log an item onto a disk log. - - Log = term() - Term = term() - Bytes = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log -

The alog/2 and balog/2 functions asynchronously append an item to a disk log. The function alog/2 is @@ -225,17 +257,13 @@ - alog_terms(Log, TermList) - balog_terms(Log, BytesList) -> ok | {error, Reason} + + Asynchronously log several items onto a disk log. - - Log = term() - TermList = [term()] - BytesList = [Bytes] - Bytes = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log - + + + +

The alog_terms/2 and balog_terms/2 functions asynchronously append a list of items to a disk log. @@ -257,14 +285,10 @@ - block(Log) - block(Log, QueueLogRecords) -> ok | {error, Reason} + + + Block a disk log. - - Log = term() - QueueLogRecords = bool() - Reason = no_such_log | nonode | {blocked_log, Log} -

With a call to block/1,2 a process can block a log. If the blocking process is not an owner of the log, a temporary @@ -280,52 +304,32 @@ affected by the block. Any other attempt than those hitherto mentioned to update or read a blocked log suspends the calling process until the log is unblocked or returns an - error message {blocked_log, Log}, depending on - whether the value of QueueLogRecords is true - or false. The default value of QueueLogRecords + error message {blocked_log, Log}, depending on + whether the value of QueueLogRecords is true + or false. The default value of QueueLogRecords is true, which is used by block/1.

- change_header(Log, Header) -> ok | {error, Reason} + Change the head or head_func option for an owner of a disk log. - - Log = term() - Header = {head, Head} | {head_func, {M,F,A}} - Head = none | term() | binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {badarg, head} -

The change_header/2 function changes the value of the head or head_func option of a disk log.

 - change_notify(Log, Owner, Notify) -> ok | {error, Reason} + Change the notify option for an owner of a disk log. - - Log = term() - Owner = pid() - Notify = bool() - Reason = no_such_log | nonode | {blocked_log, Log} | {badarg, notify} | {not_owner, Owner} -

The change_notify/3 function changes the value of the notify option for an owner of a disk log.

- change_size(Log, Size) -> ok | {error, Reason} + Change the size of an open disk log. - - Log = term() - Size = integer() > 0 | infinity | {MaxNoBytes, MaxNoFiles} - MaxNoBytes = integer() > 0 - MaxNoFiles = integer() > 0 - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {new_size_too_small, CurrentSize} | {badarg, size} | {file_error, FileName, FileError} -

The change_size/2 function changes the size of an open log. For a halt log it is always possible to increase the size, @@ -363,21 +367,17 @@ - chunk(Log, Continuation) - chunk(Log, Continuation, N) -> {Continuation2, Terms} | {Continuation2, Terms, Badbytes} | eof | {error, Reason} - bchunk(Log, Continuation) - bchunk(Log, Continuation, N) -> {Continuation2, Binaries} | {Continuation2, Binaries, Badbytes} | eof | {error, Reason} + + + + Read a chunk of items written to a disk log. - - Log = term() - Continuation = start | cont() - N = integer() > 0 | infinity - Continuation2 = cont() - Terms = [term()] - Badbytes = integer() - Reason = no_such_log | {format_external, Log} | {blocked_log, Log} | {badarg, continuation} | {not_internal_wrap, Log} | {corrupt_log_file, FileName} | {file_error, FileName, FileError} - Binaries = [binary()] - + + + + + +

The chunk/2,3 and bchunk/2,3 functions make it possible to efficiently read the terms which have been @@ -394,31 +394,31 @@ individual distributed log on some other node is chosen, if such a log exists.

-

When chunk/3 is called, N controls the +

When chunk/3 is called, N controls the maximum number of terms that are read from the log in each chunk. Default is infinity, which means that all the terms contained in the 64 kilobyte chunk are read. If less than - N terms are returned, this does not necessarily mean + N terms are returned, this does not necessarily mean that the end of the file has been reached.

The chunk function returns a tuple - {Continuation2, Terms}, where Terms is a list - of terms found in the log. Continuation2 is yet + {Continuation2, Terms}, where Terms is a list + of terms found in the log. Continuation2 is yet another continuation which must be passed on to any subsequent calls to chunk. With a series of calls to chunk it is possible to extract all terms from a log.

The chunk function returns a tuple - {Continuation2, Terms, Badbytes} if the log is opened - in read-only mode and the read chunk is corrupt. Badbytes + {Continuation2, Terms, Badbytes} if the log is opened + in read-only mode and the read chunk is corrupt. Badbytes is the number of bytes in the file which were found not to be Erlang terms in the chunk. Note also that the log is not repaired. When trying to read chunks from a log opened in read-write mode, - the tuple {corrupt_log_file, FileName} is returned if the + the tuple {corrupt_log_file, FileName} is returned if the read chunk is corrupt.

chunk returns eof when the end of the log is - reached, or {error, Reason} if an error occurs. Should + reached, or {error, Reason} if an error occurs. Should a wrap log file be missing, a message is output on the error log.

When chunk/2,3 is used with wrap logs, the returned @@ -431,12 +431,8 @@ - chunk_info(Continuation) -> InfoList | {error, Reason} + Return information about a chunk continuation of a disk log. - - Continuation = cont() - Reason = {no_continuation, Continuation} -

The chunk_info/1 function returns the following pair describing the chunk continuation returned by @@ -444,29 +440,22 @@

-

{node, Node}. Terms are read from - the disk log running on Node.

+

{node, Node}. Terms are read from + the disk log running on Node.

 - chunk_step(Log, Continuation, Step) -> {ok, Continuation2} | {error, Reason} + Step forward or backward among the wrap log files of a disk log. - - Log = term() - Continuation = start | cont() - Step = integer() - Continuation2 = cont() - Reason = no_such_log | end_of_log | {format_external, Log} | {blocked_log, Log} | {badarg, continuation} | {file_error, FileName, FileError} -

The function chunk_step can be used in conjunction with chunk/2,3 and bchunk/2,3 to search through an internally formatted wrap log. It takes as argument a continuation as returned by chunk/2,3, bchunk/2,3, or chunk_step/3, and steps forward - (or backward) Step files in the wrap log. The + (or backward) Step files in the wrap log. The continuation returned points to the first log item in the new current file.

@@ -482,11 +471,9 @@ - close(Log) -> ok | {error, Reason} + Close a disk log. - - Reason = no_such_log | nonode | {file_error, FileName, FileError} - +

The function close/1 closes a @@ -511,11 +498,8 @@ The function close/1 closes a - format_error(Error) -> Chars + Return an English description of a disk log error reply. - - Chars = [char() | Chars] -

Given the error returned by any function in this module, the function format_error returns a descriptive string @@ -524,11 +508,10 @@ The function close/1 closes a - inc_wrap_file(Log) -> ok | {error, Reason} + Change to the next wrap log file of a disk log. - - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {halt_log, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + +

The inc_wrap_file/1 function forces the internally formatted disk log to start logging to the @@ -543,8 +526,9 @@ The function close/1 closes a - info(Log) -> InfoList | {error, no_such_log} + Return information about a disk log. +

The info/1 function returns a list of {Tag, Value} pairs describing the log. If there is a disk log process running @@ -556,55 +540,55 @@ The function close/1 closes a

-

{name, Log}, where Log is the name of +

{name, Log}, where Log is the name of the log as given by the open/1 option name.

 -

{file, File}. For halt logs File is the - filename, and for wrap logs File is the base name.

+

{file, File}. For halt logs File is the + filename, and for wrap logs File is the base name.

 -

{type, Type}, where Type is the type of +

{type, Type}, where Type is the type of the log as given by the open/1 option type.

 -

{format, Format}, where Format is the format +

{format, Format}, where Format is the format of the log as given by the open/1 option format.

 -

{size, Size}, where Size is the size +

{size, Size}, where Size is the size of the log as given by the open/1 option size, or the size set by change_size/2. The value set by change_size/2 is reflected immediately.

 -

{mode, Mode}, where Mode is the mode +

{mode, Mode}, where Mode is the mode of the log as given by the open/1 option mode.

 -

{owners, [{pid(), Notify}]} where Notify +

{owners, [{pid(), Notify}]} where Notify is the value set by the open/1 option notify or the function change_notify/3 for the owners of the log.

 -

{users, Users} where Users is the number +

{users, Users} where Users is the number of anonymous users of the log, see the open/1 option linkto.

 -

{status, Status}, where Status is ok - or {blocked, QueueLogRecords} as set by the functions +

{status, Status}, where Status is ok + or {blocked, QueueLogRecords} as set by the functions block/1,2 and unblock/1.

 -

{node, Node}. The information returned by the +

{node, Node}. The information returned by the current invocation of the info/1 function has been - gathered from the disk log process running on Node.

+ gathered from the disk log process running on Node.

 -

{distributed, Dist}. If the log is local on - the current node, then Dist has the value local, +

{distributed, Dist}. If the log is local on + the current node, then Dist has the value local, otherwise all nodes where the log is distributed are returned as a list.

 @@ -614,16 +598,16 @@ The function close/1 closes a

-

{head, Head}. Depending of the value of +

{head, Head}. Depending of the value of the open/1 options head and head_func or set by the function change_header/2, the value - of Head is none (default), + of Head is none (default), {head, H} (head option) or {M,F,A} (head_func option).

 -

{no_written_items, NoWrittenItems}, where - NoWrittenItems is the number of items +

{no_written_items, NoWrittenItems}, where + NoWrittenItems is the number of items written to the log since the disk log process was created.

 @@ -632,7 +616,7 @@ The function close/1 closes a

-

{full, Full}, where Full is true or +

{full, Full}, where Full is true or false depending on whether the halt log is full or not.

 @@ -660,8 +644,8 @@ The function close/1 closes a size or set by change_size/2.

-

{no_overflows, {SinceLogWasOpened, SinceLastInfo}}, - where SinceLogWasOpened (SinceLastInfo) is +

{no_overflows, {SinceLogWasOpened, SinceLastInfo}}, + where SinceLogWasOpened (SinceLastInfo) is the number of times a wrap log file has been filled up and a new one opened or inc_wrap_file/1 has been called since the disk log was last opened (info/1 @@ -677,21 +661,18 @@ The function close/1 closes a - lclose(Log) - lclose(Log, Node) -> ok | {error, Reason} + + + Close a disk log on one node. - - Node = node() - Reason = no_such_log | {file_error, FileName, FileError} -

The function lclose/1 closes a local log or an individual distributed log on the current node. The function lclose/2 closes an individual distributed log on the specified node if the node is not the current one. - lclose(Log) is equivalent to - lclose(Log, node()). + lclose(Log) is equivalent to + lclose(Log, node()). See also close/1.

If there is no log with the given name @@ -700,20 +681,17 @@ The function close/1 closes a - log(Log, Term) - blog(Log, Bytes) -> ok | {error, Reason} + + Log an item onto a disk log. - - Log = term() - Term = term() - Bytes = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {format_external, Log} | {blocked_log, Log} | {full, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + + + +

The log/2 and blog/2 functions synchronously append a term to a disk log. They return ok or - {error, Reason} when the term has been written to + {error, Reason} when the term has been written to disk. If the log is distributed, ok is always returned, unless all nodes are down. Terms are written by means of the ordinary write() function of the @@ -736,17 +714,13 @@ The function close/1 closes a - log_terms(Log, TermList) - blog_terms(Log, BytesList) -> ok | {error, Reason} + + Log several items onto a disk log. - - Log = term() - TermList = [term()] - BytesList = [Bytes] - Bytes = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {format_external, Log} | {blocked_log, Log} | {full, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + + + +

The log_terms/2 and blog_terms/2 functions synchronously append a list of items to the log. The benefit @@ -769,47 +743,33 @@ The function close/1 closes a - open(ArgL) -> OpenRet | DistOpenRet + + + + + + + + + + Open a disk log file. - - ArgL = [Opt] - Opt = {name, term()} | {file, FileName}, {linkto, LinkTo} | {repair, Repair} | {type, Type} | {format, Format} | {size, Size} | {distributed, [Node]} | {notify, bool()} | {head, Head} | {head_func, {M,F,A}} | {mode, Mode} - FileName = string() | atom() - LinkTo = pid() | none - Repair = true | false | truncate - Type = halt | wrap - Format = internal | external - Size = integer() > 0 | infinity | {MaxNoBytes, MaxNoFiles} - MaxNoBytes = integer() > 0 - MaxNoFiles = 0 < integer() < 65000 - Rec = integer() - Bad = integer() - Head = none | term() | binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Mode = read_write | read_only - OpenRet = Ret | {error, Reason} - DistOpenRet = {[{Node, Ret}], [{BadNode, {error, DistReason}}]} - Node = BadNode = atom() - Ret = {ok, Log} | {repaired, Log, {recovered, Rec}, {badbytes, Bad}} - DistReason = nodedown | Reason - Reason = no_such_log | {badarg, Arg} | {size_mismatch, CurrentSize, NewSize} | {arg_mismatch, OptionName, CurrentValue, Value} | {name_already_open, Log} | {open_read_write, Log} | {open_read_only, Log} | {need_repair, Log} | {not_a_log_file, FileName} | {invalid_index_file, FileName} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} | {node_already_open, Log} - -

The ArgL parameter is a list of options which have +

The ArgL parameter is a list of options which have the following meanings:

-

{name, Log} specifies the name of the log. +

{name, Log} specifies the name of the log. This is the name which must be passed on as a parameter in all subsequent logging operations. A name must always be supplied.

-

{file, FileName} specifies the name of the +

{file, FileName} specifies the name of the file which will be used for logged terms. If this value is omitted and the name of the log is either an atom or a string, - the file name will default to lists:concat([Log, ".LOG"]) for halt logs. For wrap logs, this will be + the file name will default to lists:concat([Log, ".LOG"]) for halt logs. For wrap logs, this will be the base name of the files. Each file in a wrap log will be called .N]]>, where N is an integer. Each wrap log will also have two files called @@ -817,22 +777,22 @@ The function close/1 closes a

-

{linkto, LinkTo}. +

{linkto, LinkTo}. If - LinkTo is a pid, that pid becomes an owner of the - log. If LinkTo is none the log records + LinkTo is a pid, that pid becomes an owner of the + log. If LinkTo is none the log records that it is used anonymously by some process by incrementing the users counter. By default, the process which calls open/1 owns the log.

-

{repair, Repair}. If Repair is true, +

{repair, Repair}. If Repair is true, the current log file will be repaired, if needed. As the restoration is initiated, a message is output on the error log. If false is given, no automatic repair will be attempted. Instead, the - tuple {error, {need_repair, Log}} is returned if an + tuple {error, {need_repair, Log}} is returned if an attempt is made to open a corrupt log file. If truncate is given, the log file will be truncated, creating an empty log. Default is @@ -841,41 +801,41 @@ If

-

{type, Type} is the type of the log. Default +

{type, Type} is the type of the log. Default is halt.

-

{format, Format} specifies the format of the +

{format, Format} specifies the format of the disk log. Default is internal.

-

{size, Size} specifies the size of the log. +

{size, Size} specifies the size of the log. When a halt log has reached its maximum size, all attempts to log more items are rejected. The default size is infinity, which for halt implies that there is no - maximum size. For wrap logs, the Size parameter + maximum size. For wrap logs, the Size parameter may be either a pair - {MaxNoBytes, MaxNoFiles} or infinity. In the + {MaxNoBytes, MaxNoFiles} or infinity. In the latter case, if the files of an already existing wrap log with the same name can be found, the size is read from the existing wrap log, otherwise an error is returned. - Wrap logs write at most MaxNoBytes bytes on each file - and use MaxNoFiles files before starting all over with - the first wrap log file. Regardless of MaxNoBytes, + Wrap logs write at most MaxNoBytes bytes on each file + and use MaxNoFiles files before starting all over with + the first wrap log file. Regardless of MaxNoBytes, at least the header (if there is one) and one item is written on each wrap log file before wrapping to the next file. When opening an existing wrap log, it is not necessary to supply a value for the option Size, but any supplied value must equal the current size of the log, otherwise - the tuple {error, {size_mismatch, CurrentSize, NewSize}} + the tuple {error, {size_mismatch, CurrentSize, NewSize}} is returned.

-

{distributed, Nodes}. This option can be used for +

{distributed, Nodes}. This option can be used for adding members to a distributed disk log. The default value is [], which means that the log is local on the current node. @@ -946,10 +906,10 @@ If -

{head, Head} specifies a header to be +

{head, Head} specifies a header to be written first on the log file. If the log is a wrap - log, the item Head is written first in each new file. - Head should be a term if the format is + log, the item Head is written first in each new file. + Head should be a term if the format is internal, and a deep list of bytes (or a binary) otherwise. Default is none, which means that no header is written first on the file. @@ -966,17 +926,17 @@ If

-

{mode, Mode} specifies if the log is to be +

{mode, Mode} specifies if the log is to be opened in read-only or read-write mode. It defaults to read_write.

-

The open/1 function returns {ok, Log} if the +

The open/1 function returns {ok, Log} if the log file was successfully opened. If the file was - successfully repaired, the tuple {repaired, Log, {recovered, Rec}, {badbytes, Bad}} is returned, where - Rec is the number of whole Erlang terms found in the - file and Bad is the number of bytes in the file which + successfully repaired, the tuple {repaired, Log, {recovered, Rec}, {badbytes, Bad}} is returned, where + Rec is the number of whole Erlang terms found in the + file and Bad is the number of bytes in the file which were non-Erlang terms. If the distributed parameter was given, open/1 returns a list of successful replies and a list of erroneous replies. Each @@ -988,7 +948,7 @@ If position after the last logged item, and the logging of items will commence from there. If the format is internal and the existing file is not recognized as an internally - formatted log, a tuple {error, {not_a_log_file, FileName}} + formatted log, a tuple {error, {not_a_log_file, FileName}} is returned.

The open/1 function cannot be used for changing the @@ -1000,15 +960,15 @@ If or change_size/2. As a consequence, none of the options except name is mandatory. If some given value differs from the current value, a tuple - {error, {arg_mismatch, OptionName, CurrentValue, Value}} + {error, {arg_mismatch, OptionName, CurrentValue, Value}} is returned. Caution: an owner's attempt to open a log as owner once again is acknowledged with the return value - {ok, Log}, but the state of the disk log is not + {ok, Log}, but the state of the disk log is not affected in any way.

If a log with a given name is local on some node, and one tries to open the log distributed on the same node, - then the tuple {error, {node_already_open, Name}} is + then the tuple {error, {node_already_open, Log}} is returned. The same tuple is returned if the log is distributed on some node, and one tries to open the log locally on the same node. Opening individual distributed disk logs for the first time @@ -1036,12 +996,8 @@ If - pid2name(Pid) -> {ok, Log} | undefined + Return the name of the disk log handled by a pid. - - Log = term() - Pid = pid() -

The pid2name/1 function returns the name of the log given the pid of a disk log process on the current node, or @@ -1052,26 +1008,23 @@ If - reopen(Log, File) - reopen(Log, File, Head) - breopen(Log, File, BHead) -> ok | {error, Reason} + + + Reopen a disk log and save the old log. - - Log = term() - File = string() - Head = term() - BHead = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {same_file_name, Log} | {invalid_index_file, FileName} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + + + + +

The reopen functions first rename the log file - to File and then re-create a new log file. - In case of a wrap log, File is used as the base name + to File and then re-create a new log file. + In case of a wrap log, File is used as the base name of the renamed files. By default the header given to open/1 is written first in - the newly opened log file, but if the Head or the - BHead argument is given, this item is used instead. + the newly opened log file, but if the Head or the + BHead argument is given, this item is used instead. The header argument is used once only; next time a wrap log file is opened, the header given to open/1 is used.

@@ -1089,12 +1042,9 @@ If - sync(Log) -> ok | {error, Reason} + + Flush the contents of a disk log to the disk. - - Log = term() - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {file_error, FileName, FileError} -

The sync/1 function ensures that the contents of the log are actually written to the disk. @@ -1103,20 +1053,17 @@ If - truncate(Log) - truncate(Log, Head) - btruncate(Log, BHead) -> ok | {error, Reason} + + + Truncate a disk log. - - Log = term() - Head = term() - BHead = binary() | [Byte] - Byte = [Byte] | 0 =< integer() =< 255 - Reason = no_such_log | nonode | {read_only_mode, Log} | {blocked_log, Log} | {invalid_header, InvalidHeader} | {file_error, FileName, FileError} - + + + +

The truncate functions remove all items from a disk log. - If the Head or the BHead argument is + If the Head or the BHead argument is given, this item is written first in the newly truncated log, otherwise the header given to open/1 is used. The header argument is only used once; next time a wrap log file @@ -1138,12 +1085,9 @@ If - unblock(Log) -> ok | {error, Reason} + + Unblock a disk log. - - Log = term() - Reason = no_such_log | nonode | {not_blocked, Log} | {not_blocked_by_pid, Log} -

The unblock/1 function unblocks a log. A log can only be unblocked by the blocking process. @@ -1159,4 +1103,3 @@ If wrap_log_reader(3)

- -- cgit v1.2.3