File: alog-tasked_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.Task_Identification;

25.     with Alog.ExceptionsTo API docTo spec;

26.     with Alog.FacilitiesTo API docTo specTo body;

27.     with Alog.TransformsTo API docTo specTo body;

29.     --  Tasked Logger instance. Facilities can be attached to this logger instance

30.     --  in order to log to different targets simultaneously. This instance provides

31.     --  task-safe concurrent logging.

32.     package Alog.Tasked_LoggerTo API docTo specTo body is

34.        type Facility_Update_Handle is not null access

35.          procedure (Facility_Handle : Facilities.HandleTo API docTo spec);

36.        --  Handle to facility update procedure.

38.        task type InstanceTo API docTo body (Init : Boolean := False) is

40.           entry Attach_FacilityTo API docTo body (Facility : Facilities.HandleTo API docTo spec);

41.           --  Attach a facility to tasked logger instance.

43.           entry Attach_Default_FacilityTo API docTo body;

44.           --  Attach default facility to tasked logger instance.

46.           entry Detach_FacilityTo API docTo body (Name : String);

47.           --  Detach a facility from tasked logger instance.

49.           entry Detach_Default_FacilityTo API docTo body;

50.           --  Detach default facility from tasked logger instance.

52.           entry Facility_CountTo API docTo body (Count : out Natural);

53.           --  Return number of attached facilites.

55.           entry UpdateTo API docTo body

56.             (Name    : String;

57.              Process : Facility_Update_HandleTo API docTo spec);

58.           --  Update a specific facility identified by 'Name'. Calls the 'Process'

59.           --  procedure to perform the update operation.

61.           entry IterateTo API docTo body (Process : Facility_Update_HandleTo API docTo spec);

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

64.           entry Attach_TransformTo API docTo body (Transform : Transforms.HandleTo API docTo spec);

65.           --  Attach a transform to tasked logger instance.

67.           entry Detach_TransformTo API docTo body (Name : String);

68.           --  Detach a transform from tasked logger instance.

70.           entry Transform_CountTo API docTo body (Count : out Natural);

71.           --  Return number of attached transforms.

73.           entry Log_MessageTo API docTo body

74.             (Source : String := "";

75.              Level  : Log_LevelTo API docTo spec;

76.              Msg    : String;

77.              Caller : Ada.Task_Identification.Task_Id :=

78.                Ada.Task_Identification.Null_Task_Id);

79.           --  Log a message. The Write_Message() procedure of all attached

80.           --  facilities is called. Depending on the Log-Threshold set, the message

81.           --  is logged to different targets (depending on the facilites)

82.           --  automatically. If an exception occurs, the exception handler

83.           --  procedure is called.

84.           --

85.           --  If caller is not specified the executing task's ID is used instead.

86.           --  Since Log_Message'Caller can not be used as default parameter the

87.           --  entry checks if the variable is set to 'Null_Task_Id' in the body.

89.           entry ClearTo API docTo body;

90.           --  Clear tasked logger instance. Detach and teardown all attached

91.           --  facilities and transforms and clear any stored exceptions.

93.           entry ShutdownTo API docTo body;

94.           --  Explicitly shutdown tasked logger.

96.           entry Set_Except_HandlerTo API docTo body (Proc : Exceptions.Exception_HandlerTo API docTo spec);

97.           --  Set custom exception handler procedure.

99.        end InstanceTo API docTo specTo body;

100.        --  Tasked logger instance. The Init discriminant defines whether or not a

101.        --  default 'stdout' (FD facility without logfile set) is attached

102.        --  automatically. Default is 'False'. Set Init to 'True' if you want to

103.        --  make sure minimal stdout logging is possible as soon as a new logger is

104.        --  instantiated.

105.        --

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

107.        --  printed to standard error. Use the Set_Except_Handler entry to register

108.        --  a custom exception handler.

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

111.        --  Handle to tasked logger type.

113.     end Alog.Tasked_LoggerTo API docTo specTo body;