File: alog-active_logger.ads

## Documentation

Table of Contents
Class Inheritance Tree

1.     --

2.     --  Copyright (c) 2009-2011,

3.     --  Reto Buerki, Adrian-Ken Rueegsegger

4.     --

5.     --  This file is part of Alog.

6.     --

7.     --  Alog is free software; you can redistribute it and/or modify

8.     --  it under the terms of the GNU Lesser General Public License as published

9.     --  by the Free Software Foundation; either version 2.1 of the License, or

10.     --  (at your option) any later version.

11.     --

12.     --  Alog is distributed in the hope that it will be useful,

13.     --  but WITHOUT ANY WARRANTY; without even the implied warranty of

14.     --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

15.     --  GNU Lesser General Public License for more details.

16.     --

17.     --  You should have received a copy of the GNU Lesser General Public License

18.     --  along with Alog; if not, write to the Free Software

19.     --  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,

20.     --  MA  02110-1301  USA

21.     --

23.     with Ada.Finalization;

25.     with Alog.FacilitiesTo API docTo specTo body;

26.     with Alog.TransformsTo API docTo specTo body;

27.     with Alog.Tasked_LoggerTo API docTo specTo body;

28.     with Alog.Protected_ContainersTo API docTo specTo body;

29.     with Alog.ExceptionsTo API docTo spec;

31.     --  Active Logger instance. This logger is an active object and implements

32.     --  concurrent, asynchronous logging. It provides the same functionality as the

33.     --  'simple' logger.

34.     package Alog.Active_LoggerTo API docTo specTo body is

36.        type InstanceTo API docTo body (Init : Boolean) is tagged limited private;

37.        --  Active logger instance. Incoming messages (via Log_Message) are put into

38.        --  a request queue. This queue is consumed by a logging task.

39.        --

40.        --  By default exceptions which occur during asynchronous processing are

41.        --  printed to standard error. Use the Set_Except_Handler procedure to

42.        --  register a custom exception handler.

44.        type Handle is access all InstanceTo API docTo specTo body;

45.        --  Handle to active logger type.

47.        procedure Attach_FacilityTo API docTo body

48.          (LoggerTo API docTo body   : in out InstanceTo API docTo specTo body;

49.           Facility :        Facilities.HandleTo API docTo spec);

50.        --  Attach a facility to logger instance.

52.        procedure Attach_Default_FacilityTo API docTo body (LoggerTo API docTo body : in out InstanceTo API docTo specTo body);

53.        --  Attach default facility with name Default_Facility_Name to logger

54.        --  instance. If the default facility is already attached do nothing.

56.        procedure Detach_FacilityTo API docTo body

57.          (LoggerTo API docTo body : in out InstanceTo API docTo specTo body;

58.           Name   :        String);

59.        --  Detach a facility with name 'Name' from logger instance. If the facility

60.        --  is not found a Facility_Not_Found exception is raised.

62.        procedure Detach_Default_FacilityTo API docTo body (LoggerTo API docTo body : in out InstanceTo API docTo specTo body);

63.        --  Detach default facility with name Default_Facility_Name from logger

64.        --  instance. If the default facility is not attached do nothing.

66.        function Facility_CountTo API docTo body (LoggerTo API docTo body : InstanceTo API docTo specTo body) return Natural;

67.        --  Return number of attached facilites.

69.        procedure UpdateTo API docTo body

70.          (LoggerTo API docTo body  : in out InstanceTo API docTo specTo body;

71.           Name    :        String;

72.           Process :        Tasked_Logger.Facility_Update_HandleTo API docTo spec);

73.        --  Update a specific Facility identified by 'Name'. Call the 'Process'

74.        --  procedure to perform the update operation.

76.        procedure IterateTo API docTo body

77.          (LoggerTo API docTo body  : in out InstanceTo API docTo specTo body;

78.           Process :        Tasked_Logger.Facility_Update_HandleTo API docTo spec);

79.        --  Call 'Process' for all attached facilities.

81.        procedure Attach_TransformTo API docTo body

82.          (LoggerTo API docTo body    : in out InstanceTo API docTo specTo body;

83.           Transform :        Transforms.HandleTo API docTo spec);

84.        --  Attach a transform to logger instance.

86.        procedure Detach_TransformTo API docTo body

87.          (LoggerTo API docTo body : in out InstanceTo API docTo specTo body;

88.           Name   :        String);

89.        --  Detach a transform with name 'Name' from logger instance. If the

90.        --  transform is not found a Transform_Not_Found exception is raised.

92.        function Transform_CountTo API docTo body (LoggerTo API docTo body : InstanceTo API docTo specTo body) return Natural;

93.        --  Return number of attached transforms.

95.        procedure ClearTo API docTo body (LoggerTo API docTo body : in out InstanceTo API docTo specTo body);

96.        --  Clear logger instance. Detach and teardown all attached facilities and

97.        --  transforms.

99.        procedure Log_MessageTo API docTo body

100.          (LoggerTo API docTo body : in out InstanceTo API docTo specTo body;

101.           Source :        String := "";

102.           LevelTo API docTo body  :        Log_LevelTo API docTo spec;

103.           Msg    :        String);

104.        --  Log the given message asynchronously. The message is put into a log

105.        --  request queue which is continuously consumed by a logging task.

106.        --

107.        --  This procedure is *safe* to call from protected actions (e.g. from an

108.        --  entry call statement or rendezvous).

110.        function Get_Queue_LengthTo API docTo body (LoggerTo API docTo body : InstanceTo API docTo specTo body) return Natural;

111.        --  Returns the number of currently queued log messages.

113.        procedure ShutdownTo API docTo body

114.          (LoggerTo API docTo body : in out InstanceTo API docTo specTo body;

115.           Flush  :        Boolean := True);

116.        --  Shutdown the active logger. This procedure must be called in order for

117.        --  the logger task to be terminated properly. If 'Flush' is set to True the

118.        --  procedure will wait for all queued messages to be logged.

120.        function Is_TerminatedTo API docTo body (LoggerTo API docTo body : InstanceTo API docTo specTo body) return Boolean;

121.        --  Returns True if active logger shutdown sequence is complete.

123.        procedure All_DoneTo API docTo body (LoggerTo API docTo body : in out InstanceTo API docTo specTo body);

124.        --  This procedure blocks until all queued logging requests have been

125.        --  consumed.

127.        procedure Set_Except_HandlerTo API docTo body

128.          (LoggerTo API docTo body : InstanceTo API docTo specTo body;

129.           Proc   : Exceptions.Exception_HandlerTo API docTo spec);

130.        --  Set custom exception handler procedure.

132.        type Shutdown_HelperTo API docTo body (LoggerTo API docTo specTo body : not null access InstanceTo API docTo specTo body) is private;

133.        --  This helper will call Shutdown on the logger given as discriminant when

134.        --  it goes out of scope. This relieves the user from having to excplicitly

135.        --  call shutdown on an instance of Alog active logger when wanting to

136.        --  terminate. Users must make sure to declare any shutdown helper in a

137.        --  smaller scope than the active logger on which the helper supposed to

138.        --  work.

140.     private

142.        task type Logging_Task (Parent : not null access InstanceTo API docTo specTo body);

143.        --  This task takes logging requests from the parent's message queue and

144.        --  logs them using the parent's backend logger.

146.        protected type Trigger_Type is

147.           procedure Shutdown;

148.           entry Stop;

149.        private

150.           Shutdown_Requested : Boolean := False;

151.        end Trigger_Type;

152.        --  This trigger is used to terminate the logger task by means of ATC.

154.        type InstanceTo API docTo spec (Init : Boolean) is tagged limited record

155.           Logger_Task   : Logging_Task (Parent => InstanceTo API docTo specTo body'Access);

156.           Backend       : Tasked_Logger.InstanceTo API docTo specTo body (Init);

157.           Message_Queue : Protected_Containers.Log_Request_ListTo API docTo spec;

158.           Trigger       : Trigger_Type;

159.        end record;

161.        type Shutdown_HelperTo API docTo spec (LoggerTo API docTo specTo body : not null access InstanceTo API docTo specTo body) is

162.          new Ada.Finalization.Controlled with null record;

164.        overriding

165.        procedure Finalize (Helper : in out Shutdown_HelperTo API docTo specTo body);

166.        --  Call shutdown on the active logger instance specified as discriminat.

168.     end Alog.Active_LoggerTo API docTo specTo body;