1--
2--  Copyright (c) 2009-2012,
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--
22
23with Ada.Task_Identification;
24
25with Alog.Exceptions;
26with Alog.Facilities;
27with Alog.Transforms;
28
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.
32package Alog.Tasked_Logger is
33
34   type Facility_Update_Handle is not null access
35     procedure (Facility_Handle : Facilities.Handle);
36   --  Handle to facility update procedure.
37
38   task type Instance (Init : Boolean := False) is
39
40      entry Attach_Facility (Facility : Facilities.Handle);
41      --  Attach a facility to tasked logger instance.
42
43      entry Attach_Default_Facility;
44      --  Attach default facility to tasked logger instance.
45
46      entry Detach_Facility (Name : String);
47      --  Detach a facility from tasked logger instance.
48
49      entry Detach_Default_Facility;
50      --  Detach default facility from tasked logger instance.
51
52      entry Facility_Count (Count : out Natural);
53      --  Return number of attached facilites.
54
55      entry Update
56        (Name    : String;
57         Process : Facility_Update_Handle);
58      --  Update a specific facility identified by 'Name'. Calls the 'Process'
59      --  procedure to perform the update operation.
60
61      entry Iterate (Process : Facility_Update_Handle);
62      --  Call 'Process' for all attached facilities.
63
64      entry Attach_Transform (Transform : Transforms.Handle);
65      --  Attach a transform to tasked logger instance.
66
67      entry Detach_Transform (Name : String);
68      --  Detach a transform from tasked logger instance.
69
70      entry Transform_Count (Count : out Natural);
71      --  Return number of attached transforms.
72
73      entry Log_Message
74        (Level  : Log_Level;
75         Msg    : String;
76         Source : 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.
88
89      entry Clear;
90      --  Clear tasked logger instance. Detach and teardown all attached
91      --  facilities and transforms and clear any stored exceptions.
92
93      entry Shutdown;
94      --  Explicitly shutdown tasked logger.
95
96      entry Set_Except_Handler (Proc : Exceptions.Exception_Handler);
97      --  Set custom exception handler procedure.
98
99   end Instance;
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.
109
110   type Handle is access all Instance;
111   --  Handle to tasked logger type.
112
113end Alog.Tasked_Logger;
114