forked from gnustep/libs-ec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathEcProcess.h
1447 lines (1292 loc) · 59.1 KB
/
EcProcess.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/** Enterprise Control Configuration and Logging
Copyright (C) 2012 Free Software Foundation, Inc.
Written by: Richard Frith-Macdonald <[email protected]>
Date: Febrary 2010
Originally developed from 1996 to 2012 by Brainstorm, and donated to
the FSF.
This file is part of the GNUstep project.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 3 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02111 USA.
*/
#ifndef INCLUDED_ECPROCESS_H
#define INCLUDED_ECPROCESS_H
#import <Foundation/Foundation.h>
#import "EcAlarm.h"
#import "EcAlarmDestination.h"
/** Convenience macros to raise unique alarms (which do not clear automatically)
* for exceptions or unexpected code/data errors. The unique specificProblem
* for each alarm is derived from the file and line at which it is raised.
* These macros should only be used when it's impossible/impractical to have
* the code automatically detect that a problem has gone away, and clear the
* alarm.
*/
#define EcExceptionCritical(cause, format, args...) \
({ if (nil == EcProc) NSLog(@"%@",\
[NSString stringWithFormat: @"%s at %@ line %d ... %@", \
(nil == (cause) ? "Code/Data Error (critical)" : "Exception"), \
[[NSString stringWithUTF8String: __FILE__] lastPathComponent], __LINE__, \
[NSString stringWithFormat: (format), ##args]]); else \
[EcProc ecException: (cause) \
specificProblem: [NSString stringWithFormat: @"%s at %@ line %d", \
(nil == (cause) ? "Code/Data Error (critical)" : "Exception"), \
[[NSString stringWithUTF8String: __FILE__] lastPathComponent], __LINE__] \
perceivedSeverity: EcAlarmSeverityCritical \
message: (format), ##args ]; \
})
#define EcExceptionMajor(cause, format, args...) \
({ if (nil == EcProc) NSLog(@"%@",\
[NSString stringWithFormat: @"%s at %@ line %d ... %@", \
(nil == (cause) ? "Code/Data Error" : "Exception"), \
[[NSString stringWithUTF8String: __FILE__] lastPathComponent], __LINE__, \
[NSString stringWithFormat: (format), ##args]]); else \
[EcProc ecException: (cause) \
specificProblem: [NSString stringWithFormat: @"%s at %@ line %d", \
(nil == (cause) ? "Code/Data Error" : "Exception"), \
[[NSString stringWithUTF8String: __FILE__] lastPathComponent], __LINE__] \
perceivedSeverity: EcAlarmSeverityMajor \
message: (format), ##args ]; \
})
#define EcExceptionMinor(cause, format, args...) \
({ if (nil == EcProc) NSLog(@"%@",\
[NSString stringWithFormat: @"%s at %@ line %d ... %@", \
(nil == (cause) ? "Code/Data Error (minor)" : "Exception"), \
[[NSString stringWithUTF8String: __FILE__] lastPathComponent], __LINE__, \
[NSString stringWithFormat: (format), ##args]]); else \
[EcProc ecException: (cause) \
specificProblem: [NSString stringWithFormat: @"%s at %@ line %d", \
(nil == (cause) ? "Code/Data Error (minor)" : "Exception"), \
[[NSString stringWithUTF8String: __FILE__] lastPathComponent], __LINE__] \
perceivedSeverity: EcAlarmSeverityMinor \
message: (format), ##args ]; \
})
/* Diagnostic logging including a stack trace (either from an exception or,
* if the exception is nil, from the point at which the log is generated.
* This is like the other EcException macros, except that it does not
* generate an alarm.
*/
#define EcExceptionDebug(cause, format, args...) \
({ if (nil == EcProc) NSLog(@"%@",\
[NSString stringWithFormat: @"%s at %@ line %d ... %@", \
(nil == (cause) ? "Code/Data Diagnostics" : "Harmless Exception"), \
[[NSString stringWithUTF8String: __FILE__] lastPathComponent], __LINE__, \
[NSString stringWithFormat: (format), ##args]]); else \
[EcProc ecException: (cause) \
specificProblem: [NSString stringWithFormat: @"%s at %@ line %d", \
(nil == (cause) ? "Code/Data Diagnostics" : "Harmless Exception"), \
[[NSString stringWithUTF8String: __FILE__] lastPathComponent], __LINE__] \
perceivedSeverity: EcAlarmSeverityCleared \
message: (format), ##args ]; \
})
@class NSFileHandle;
typedef enum {
LT_DEBUG, /* Debug message - internal info. */
LT_WARNING, /* Warning - possibly a real problem. */
LT_ERROR, /* Error - needs dealing with. */
LT_AUDIT, /* Not a problem but needs logging. */
LT_ALERT, /* Severe - needs immediate attention. */
LT_CONSOLE, /* For Console (implicit audit). */
} EcLogType;
/**
* A 'ping' can be sent from or to any process to check that it is alive.
* A 'gnip' should be sent in response to each 'ping'
* Each 'ping' carries a sequence number which should be echoed in its 'gnip'.
* Optionally, the 'ping' can also transport a serialized property-list
* to provide additional data or instructions - the value of which is
* dependent on the program being pinged - normally this value is nil.
*/
@protocol CmdPing
- (oneway void) cmdGnip: (id <CmdPing>)from
sequence: (unsigned)num
extra: (in bycopy NSData*)data;
- (oneway void) cmdPing: (id <CmdPing>)from
sequence: (unsigned)num
extra: (in bycopy NSData*)data;
@end
/** The CmdConfig protocol is needed by objects that send and receive
* configuration information.
*/
@protocol CmdConfig
- (oneway void) requestConfigFor: (id<CmdConfig>)c;
- (oneway void) updateConfig: (in bycopy NSData*)info;
@end
@protocol EcConfigForwarded;
/** The EcConfigForwarding protocol is provided by a process to allow
* cooperating client processes to know how it is configured and to get
* automatic updates when its configuration changes.
*/
@protocol EcConfigForwarding <NSObject>
/** This method may be called by a client when it wishes to stop receiving
* configuraton updates from the server.
*/
- (oneway void) ecCancelConfigFwdTo: (id<EcConfigForwarded>)client;
/** This method is called by the client when it wants to start receiving
* configuration updates from the server. The method returns the current
* configuration of the server (at the point when the method was called).
* NB. With multithreaded applications it is possible that setting up
* configuration forwarding could cause a client to be informed of a
* configuration change before the setup method returns the configuration.
*/
- (bycopy NSDictionary*) ecSetupConfigFwdTo: (id<EcConfigForwarded>)client;
@end
/** This is the protocol to which a client of configuration forwarding must
* confirm. It contains a single method that the server calls to pass config
* to the client.
*/
@protocol EcConfigForwarded <NSObject>
- (oneway void) ecForwardedConfig: (in bycopy NSDictionary*)info
from: (id<EcConfigForwarding>)server;
@end
/** Messages that the Command server may send to clients.
*/
@protocol CmdClient <CmdPing,CmdConfig>
/** Passes a property list message to the client (eg from the Console).
*/
- (oneway void) cmdMesgData: (in bycopy NSData*)dat from: (NSString*)name;
/** Tells the client to shut down.
*/
- (oneway void) cmdQuit: (NSInteger)status;
/** Asks the client for its process identifier.
*/
- (int) processIdentifier;
/** Asks the client whether it is awake (-ecAwaken has been called)
*/
- (BOOL) ecDidAwaken;
/** Instructs the client process to connect and re-register with the Command
* server.
*/
- (oneway void) ecReconnect;
@end
/** Messages a Command logging process can be expected to handle.
*/
@protocol CmdLogger <CmdClient>
- (void) flush;
- (oneway void) logMessage: (NSString*)msg
type: (EcLogType)t
name: (NSString*)c;
- (oneway void) logMessage: (NSString*)msg
type: (EcLogType)t
for: (id)o;
- (bycopy NSData*) registerClient: (id)c
identifier: (int)p
name: (NSString*)n
transient: (BOOL)t;
- (void) unregisterByObject: (byref id)obj status: (int)s;
- (void) woken: (id)obj;
@end
@protocol Console <NSObject>
- (oneway void) information: (NSString*)txt;
@end
/** Messages that clients may send to the server.
* NB. The -registerClient:identifier:name:transient: method must be sent
* before the -command:to:from: or -reply:to:from: methods.
*/
@protocol Command <CmdLogger,CmdConfig,EcAlarmDestination>
/** Request a count of the active clients of the Command server
*/
- (unsigned) activeCount;
/** Pass an alarm to the Command server for forwarding to the Control
* server for central handling to send alerts or SNMP integration.
*/
- (oneway void) alarm: (in bycopy EcAlarm*)alarm;
/** Pass an alarm clear to the Command server for forwarding to its
* clients for clearing.
*/
- (oneway void) clear: (in bycopy EcAlarm*)alarm;
/** Send a text command to a process owned by the Command server.
*/
- (oneway void) command: (in bycopy NSData*)dat
to: (NSString*)t
from: (NSString*)f;
/** Request immediate launch of the named process.<br />
* Returns NO if the process cannot be launched.<br />
* Returns YES if the process is already running or launching has started.
*/
- (BOOL) launch: (NSString*)name;
/** Registers as a client process of the Command server.
*/
- (bycopy NSData*) registerClient: (id)c
identifier: (int)p
name: (NSString*)n
transient: (BOOL)t;
/** Replies to a text command sent by another process.
*/
- (oneway void) reply: (NSString*)msg
to: (NSString*)n
from: (NSString*)c;
/** Shut down the Command server and all its clients.<br />
* Clients which fail to shut down gracefully before the specified timestamp
* will be forcibly killed. The timestamp is constrained to be at least half
* a second in the future and not more than 15 minutes in the future.
*/
- (oneway void) terminate: (NSDate*)byDate;
/** This is meant to be used remotely by all sorts of software running
* on the machine and which is *not* a full Command client (ie, not a
* subclass of EcProcess) but which still wants to retrieve
* configuration from a central location (the Control/Command servers).<br />
* The returned value is a a serialized property list ... you need to
* deserialize using the standard GNUstep property list APIs.<br />
* NB: The configuration might change later on, so you must not cache
* the configuration after asking for it, but rather ask for it each
* time your software needs it.
*/
- (bycopy NSData *) configurationFor: (NSString *)name;
/** Informs the Command server that a previously registered client considers
* itself to have started up and to now be stable.
*/
- (void) woken: (id)obj;
@end
/*
* Messages that clients may send to the server.
*/
@protocol Control <CmdPing,CmdConfig,EcAlarmDestination>
- (oneway void) alarm: (in bycopy EcAlarm*)alarm;
- (oneway void) command: (in bycopy NSData*)cmd
from: (NSString*)f;
- (oneway void) domanage: (NSString*)name;
- (oneway void) information: (NSString*)msg
type: (EcLogType)t
to: (NSString*)to
from: (NSString*)from;
- (bycopy NSData*) registerCommand: (id<Command>)c
name: (NSString*)n;
- (bycopy NSString*) registerConsole: (id<Console>)c
name: (NSString*)n
pass: (NSString*)p;
- (oneway void) reply: (NSString*)msg
to: (NSString*)n
from: (NSString*)c;
- (oneway void) servers: (in bycopy NSData*)a
on: (id<Command>)s;
- (oneway void) unmanage: (NSString*)name;
- (void) unregister: (id)o;
@end
/*
* Useful functions -
*/
extern void cmdSetHome(NSString *home);
extern NSString* cmdDataDir();
extern NSString* cmdLogsDir(NSString *date);
extern NSString* cmdLogKey(EcLogType t);
extern NSString* cmdLogName();
extern NSString* cmdLogFormat(EcLogType t, NSString *fmt);
extern void ecSetLogsSubdirectory(NSString *pathComponent);
/** Return the native thread ID of the current thread, or NSNotFound if
* that is not available.
*/
extern NSUInteger ecNativeThreadID();
/* Set/get version/compilation date.
*/
extern NSString* cmdVersion(NSString *ver);
/**
* Command line arguments -
*
*
* <p>On startup, these are taken from the command line, or from the
* local user defaults database of the person running the program.<br />
* If the EcEffectiveUser specifies an alternative user, or the
* program is able to read the database for the 'ecuser' user, then
* the other values are read from the defaults database of that user.
* </p>
* <p>After startup, the command line arguments still take precedence,
* but values retrieved from the network configuration system will
* then override any read from the local user defaults database.
* </p>
* <p>Settings in the network configuration system will have no effect on
* the following defaults which are used BEFORE the network configuration
* can be read.
* </p>
* <deflist>
* <term>EcCoreSize</term>
* <desc>
* Specifies the maximum size (in MB) for any core-dump of the
* process.<br />
* If this is not set, the default size of 2GB is used.<br />
* If this is negative, the size is unlimited.<br />
* If this is zero then no core dumping is performed.
* </desc>
* <term>EcDaemon</term>
* <desc>To specify whether the program should run in the background
* (boolean, YES if the program is to run as a daemon, NO otherwise).<br />
* The value in the network configuration has no effect.
* </desc>
* <term>EcEffectiveUser</term>
* <desc>To tell the server to change to being this user on startup.
* defaults to 'ecuser', but the default can be overridden by specifying
* '-DEC_EFFECTIVE_USER+@"username"' in the local.make make file.<br />
* Set a value of '*' to remain whoever runs the program
* rather than changing.
* </desc>
* <term>EcInstance</term>
* <desc>To set the program instance ID (a non-negative integer value).<br />
* If this is specified, the program name has a hyphen and the
* id appended to it by the '-initWithDefaults:' method.
* </desc>
* <term>EcKeepStandardError</term>
* <desc>
* This boolean value determines whether the standard error output
* should be kept as it is on process startup, or should be merged
* with the local debug log to file.<br />
* The default (EcKeepStandardError set to NO) is to merge the
* standard error logging with the debug logging.
* </desc>
* <term>EcKillDebugOutput</term>
* <desc>
* This boolean value determines whether debug output (including anything
* written to the standard error output if that is merged with debug)
* should be discarded (sent to the null device).<br />
* This setting cannot e controlled from the Console command line.<br />
* The default (EcKillDebugOutput set to NO) is to write debug output to
* file.
* </desc>
* <term>EcTransient</term>
* <desc>
* This boolean option is used to specify that the program
* should not be restarted automatically by the Command
* server if/when it disconnects from that server.
* </desc>
* </deflist>
* <p>The following settings will be revised after startup to include the
* values from the network configuration system.
* </p>
* <deflist>
* <term>EcAuditFlush</term>
* <desc>A flush interval in seconds (optionally followed by a colon
* and a buffer size in KiloBytes) to control flushing of audit logs.<br />
* Setting an interval of zero or less disables flushing by timer.<br />
* Setting a size of zero or less, disables buffering (so logs are
* flushed immediately).
* </desc>
* <term>EcDebug-</term>
* <desc>
* Any key of the form EcDebug-xxx turns on the xxx debug level
* on program startup.<br />
* The value of 'XXX' must match the name of a debug mode used
* by the program!
* </desc>
* <term>EcDescriptorsMaximum</term>
* <desc>
* To protect against file descriptor leaks, a process will
* check for the ability to create a pipe once a minute.<br />
* If it can't do so, it will shut down with an error message.<br />
* To increase the chances of a successful shutdown, two
* descriptors are reserved on the first check, and closed
* when a shutdown is attempted.<br />
* If EcDescriptorsMaximum is defined to a positive integer value,
* it is used to trigger earlier shutdown once the specified
* number of open file descriptors has been reached, rather
* than waiting for the operating system imposed limit.
* </desc>
* <term>EcMemory</term>
* <desc>
* This boolean value determines whether statistics on creation
* and destruction of objects are maintained.<br />
* This may be set in the NSUserDefaults system or in Control.plist,
* but may be overridden by using the 'memory' command in the
* Console program.
* </desc>
* <term>EcMemoryAlarm</term>
* <desc>
* This may be used to control the alarm severity level at which the
* system starts raising alarms about memory usage. Setting it to Warning
* means that alarms are raised as soon as the base/allowed memory limit
* is passed, while setting it to Critical only causes an alarm to be
* raised when the MemoryMaximum limit is close.<br />
* The default value is Major (the possible values are Warning, Minor,
* Major, and Critical).<br />
* This may be set in the NSUserDefaults system or in Control.plist,
* but may be overridden by using the 'memory' command in the
* Console program.
* </desc>
* <term>EcMemoryAllowed</term>
* <desc>
* This may be used to specify the process memory usage
* (in megabytes by default) before memory usage alarms may begin.<br />
* If this setting is not specified (or a negative or excessive value
* is specified) then memory is monitored for ten minutes and the
* base/allowed threshold is set at either the peak during that period
* (plus a twenty percent margin to allow further memory growth) or at
* half the MemoryMaximum value, whichever is the greater.<br />
* This may be set in the NSUserDefaults system or in Control.plist,
* but may be overridden by using the 'memory' command in the
* Console program.
* </desc>
* <term>EcMemoryIdle</term>
* <desc>
* This optional integer value (0 to 23) may be used to specify the hour
* of the day in which restarts are preferred to take place (some time
* when the process is likely to be idle). If a process is near a
* maximum permitted memory usage at this time of day,
* the -ecRestart: method will be called.<br />
* Near means over three quarters of the way between the base/allowed
* memory usage (as determined by MemoryAllowed) and MemoryMaximum.<br />
* This may be set in the NSUserDefaults system or in Control.plist,
* but may be overridden by using the 'memory' command in the
* Console program.
* </desc>
* <term>EcMemoryMaximum</term>
* <desc>
* This may be used to specify the maximum process memory allowed
* (in megabytes by default) before the process is forced to restart due
* to excessive memory usage.<br />
* If the total memory usage of the process reaches this threshold,
* the -ecRestart: method will be called<br />
* The process will also generate alarms depending on the memory usage
* once the bas/allowed memory usge has been passed. The severity of
* the alarms depends on how far from the base/allowed memory to the
* maximum memory the current ten minute average of the usage is.<br />
* This may be set in the NSUserDefaults system or in Control.plist,
* but may be overridden by using the 'memory' command in the
* Console program.
* </desc>
* <term>EcMemoryType</term>
* <desc>
* This controls the type of memory considered by the EcMemoryAllowed,
* EcMemoryIdle and EcMemoryMaximum options.<br />
* Total (the default), considers the total process memory usage.<br />
* Resident, considers current resident memory used.<br />
* Data, considers only dynamically allocated and stack memory.<br />
* While using Total and Resident are easy to relate to the output of
* system tools such as <code>ps</code> and <code>top</code>, the Data
* memory type is probably of most use for tracking memory leaks on a
* system with many processes running, since it excludes memory shared
* between multiple processes (used for the program code and for shared
* libraries).
* </desc>
* <term>EcMemoryUnit</term>
* <desc>
* This controls the units in which memory information is displayed,
* the default being K/KB/KiB (1024 bytes). Other possible settings are
* M/MB/MiB (1048576 bytes) and P/Pg/Page (system memory pages, typically
* 4096 bytes).
* </desc>
* <term>EcRelease</term>
* <desc>
* This boolean value determines whether checks for memory problems
* caused by release an object too many times are done. Turning
* this on has a big impact on program performance and is not
* recommended except for debugging crashes and other memory
* issues.<br />
* This may be set in the NSUserDefaults system or in Control.plist,
* but may be overridden by using the 'release' command in the
* Console program.
* </desc>
* <term>EcTesting</term>
* <desc>
* This boolean value determines whether the server is running in
* test mode (which may enable extra logging or prevent the server
* from communicating with live systems etc ... the actual
* behavior is server dependent).<br />
* This may be set on the command line or in Control.plist, but
* may be overridden by using the 'testing' command in the
* Console program.
* </desc>
* <term>EcWellKnownHostNames</term>
* <desc>A dictionary mapping host names/address values to well known
* names (the canonical values used by Command and Control).
* </desc>
* </deflist>
* Alarm mechanism
* <p>
* The EcProcess class conforms to the EcAlarmDestination protocol
* to allow sending alarm information to a centralised alarm system
* via the Command server (the Control server acts as a sink for
* those alarms and provides SNMP integration).
* </p>
* <p>
* In addition to the standard alarm destination behavior, the
* process automates some things:<br />
* On successful startup and registration with the Command server,
* a -domanage: message is automatically sent for the default
* managed object, clearing any outstanding alarms.<br />
* On successful shutdown (ie when -cmdQuit: is called with zero
* as its argument), an -unmanage: message is automatically sent
* to clear any outstanding alarms for the default managed object.<br />
* If you want to raise alarms which will persist after a successful
* shutdown you should therefore do so by creating a different managed
* object for which to raise those alarms.
* </p>
* <p>As a convenience, the class provides various methods to raise different
* kinds of alarms for specific common purposes:
* </p>
* <deflist>
* <term>Configuration problems</term>
* <desc>-alarmConfigurationFor:specificProblem:additionalText:critical:
* </desc>
* <term>Exceptions and unexpected errors</term>
* <desc>-ecException:specificProblem:perceivedSeverity:message:,...
* </desc>
* </deflist>
* <p>
* To further aid with logging/alarming about unexpected code and data
* problems, there are macros to provide detailed logs as well as
* specific alarms of different severity.
* </p>
*/
@interface EcProcess : NSObject <CmdClient,EcAlarmDestination,
EcConfigForwarding>
{
/** Any method which is executing in the main thread (and needs to
* return before a quit can be handled in the main thread) must
* increment this counter on entry and decrement it again before exit.
* This allows the process to ensure that it calls -ecHandleQuit when
* no such method is in progress.
*/
NSUInteger ecDeferQuit;
}
/** This method is provided to prompt for an encryption key using the
* specified key name and read in a value from the terminal.<br />
* The entered value must be an even numbered sequence of hexadecimal
* digits, each pair representing one byte of the key.<br />
* The key length (number of bytes) must be the specified size, a value
* between 16 and 128, which is exactly half the number of hexadecimal
* digits that must be entered.<br />
* If the digest is not supplied, the user will be required to
* enter the value twice (and the two values must match) for
* confirmation.<br />
* If the digest is supplied, the md5 digest of the entered key must
* match it (but the user does not need to enter the value twice).
*/
+ (NSString*) ecGetKey: (const char*)name
size: (unsigned)size
md5: (NSData*)digest;
/** Provides initial configuration.
* This method is used by -init and its return value is passed to
* -initWithDefaults: method.<br />
* The default implementation simply sets the ProgramName and
* HomeDirectory defaults to the current program name and
* the current directory ('.').<br />
* Subclasses may override this method to provide additional
* default configuration for processes using them. The returned
* dictionary is mutable so that a subclass may simply modify
* the configuration provided by the superclass implementation.
*/
+ (NSMutableDictionary*) ecInitialDefaults;
/** Returns the lock used by the -ecDoLock and -ecUnLock methods.
*/
+ (NSRecursiveLock*) ecLock;
/** Registers an NSUserDefaults key that the receiver understands.<br />
* This is primarily intended for user defaults which can reasonably
* be supplied at the command line when a process is started (and for
* which the process should therefore supply help information).<br />
* The type text must be a a short string saying what kind of value
* must be provided (eg 'YES/NO') for the default, or nil if no help
* is to be provided for the default.<br />
* The help text should be a description of what the default does,
* or nil if no help is to be provided for the default.<br />
* The action may either be NULL or a selector for a message to be sent
* to the EcProc instance with a single argument (the new default value)
* when the value of the user default changes.<br />
* The value may either be NULL, or be an object to be set in the registration
* domain of the defaults system (as long as this method is called before
* the EcProcess instance is initialized).<br />
* If the same default name is registered more than once, the values
* from the last registration are used, except for the case where the
* cmd argument is NULL, in that case the previous selector is kept
* in the new registration.<br />
* This method should be called in your +initialize method, so that all
* supported defaults are already registered by the time your process
* tries to respond to being started with a --help command line argument.<br />
* NB. defaults keys do not have to be registered (and can still be updated
* using the 'defaults' command), but registration provides a more user
* friendly interface.<br />
* If this method is called later (once the EcProcess instance has been
* initialized) it will not update the current user defaults until you also
* call the -ecUpdateRegisteredDefaults method.
*/
+ (void) ecRegisterDefault: (NSString*)name
withTypeText: (NSString*)type
andHelpText: (NSString*)help
action: (SEL)cmd
value: (id)value;
/** Convenience method to create the singleton EcProcess instance
* using the initial configuration provided by the +ecInitialDefaults
* method.<br />
* Raises NSGenericException if the singleton instance has already
* been created.
*/
+ (void) ecSetup;
/** Convenience method to produce a generic configuration alarm and send
* it via the -alarm: method.<br />
* The managed object may be nil (in which case it's the default managed object
* for the current process).<br />
* The implied event type is EcAlarmEventTypeProcessingError.<br />
* The implied probable cause is EcAlarmConfigurationOrCustomizationError.<br />
* The implied severity is EcAlarmSeverityMajor unless isCritical is YES.<br />
* The implied trend is EcAlarmTrendNone.<br />
* The implied proposed repair action is to check/correct the config.<br />
* The specific problem and additional text should be used to suggest
* what is wrong with the config and where the config error should be
* found/corrected.
*/
- (EcAlarm*) alarmConfigurationFor: (NSString*)managedObject
specificProblem: (NSString*)specificProblem
additionalText: (NSString*)additionalText
critical: (BOOL)isCritical;
/** Returns the array of current alarms.
*/
- (NSArray*) alarms;
/** Convenience method to clear an alarm as produced by the
* -alarmConfigurationFor:specificProblem:additionalText:critical:
* method.
*/
- (void) clearConfigurationFor: (NSString*)managedObject
specificProblem: (NSString*)specificProblem
additionalText: (NSString*)additionalText;
/** Returns the alarm destination for this process.
*/
- (EcAlarmDestination*) ecAlarmDestination;
/** Return a short copyright notice ... subclasses should override.
*/
- (NSString*) ecCopyright;
/** Obtain a lock on the shared EcProcess for thread-safe updates to
* process-wide variables.
*/
- (void) ecDoLock;
/** Called once other stages of a graceful shutdown has completed in
* order to perform final cleanup and have the process exit with the
* expected status.<br />
* Called automatically in the main thread by the -ecHandleQuit method.
* Subclasses overriding -ecDidQuit must call the superclass
* implementation at the end of their handling code.
*/
- (oneway void) ecDidQuit;
/** Called by -ecQuitFor:with: or -cmdQuit: (after the -ecWillQuit and
* before the -ecDidQuit methods) as a method for subclasses to use to
* implement their own behaviors.<br />
* Subclass implementations should call the superclass implementation
* as the last thing they do.<br />
* This method is always called in the main thread of the process and
* when the ecDeferQuit instance variable is zero.
*/
- (void) ecHandleQuit;
/** Returns YES if the process is attempting a graceful shutdown,
* NO otherwise. This also checks to see if the process has been
* attempting to shut down for too long, and if it has been going
* on for over three minutes (or the value set by -ecQuitLimit:),
* aborts the process.<br />
* Subclasses must not override this method.
*/
- (BOOL) ecIsQuitting;
/** Returns the interval since the process started quitting, or zero
* if it is not quitting (as determined by calling -ecIsQuitting).
*/
- (NSTimeInterval) ecQuitDuration;
/** This method is designed for handling an orderly shutdown by noting
* the supplied reason and status, and then calling -ecWillQuit,
* -ecHandleQuit, and finally calling -ecDidQuit.<br />
* Subclasses should not normally override this method. Instead override
* the -ecHandleQuit method.<br />
* For backward compatibility, this will call the -cmdQuit: method if a
* subclass has overridden it.<br />
* NB. On unix the possible range of status values is actually from -128
* to 127 and we have certain conventions:
* <deflist>
* <term>0</term>
* <desc>A clean/normal shutdown, no restart required</desc>
* <term>-1</term>
* <desc>An intentional shutdown where restart is required</desc>
* <term>-2</term>
* <desc>Process unable to register with name server</desc>
* <term>-3</term>
* <desc>Fatal error in process configuration information</desc>
* <term>-4</term>
* <desc>Process registration was rejected by the Command server</desc>
* <term>-5 to -9</term>
* <desc>Reserved for possible expansion</desc>
* <term>-10 to -128</term>
* <desc>Unused/free</desc>
* <term>positive integer</term>
* <desc>Process caught a unix signal and shut down; the exist status
* is the number of that signal</desc>
* </deflist>
*/
- (oneway void) ecQuitFor: (NSString*)reason with: (NSInteger)status;
/** Sets the number of seconds the graceful shutdown process is permitted
* to take before the process will attempt to abort on the next check to
* see if it quitting (-ecIsQuitting). The default is 180.0 seconds.<br />
* This method returns the previous value of the setting.
*/
- (NSTimeInterval) ecQuitLimit: (NSTimeInterval)seconds;
/** Returns the quit reason supplied to the -ecQuitFor:with: method.
*/
- (NSString*) ecQuitReason;
/** Returns the quit status supplied to the -ecQuitFor:with: or -cmdQuit:
* method.
*/
- (NSInteger) ecQuitStatus;
/** This method may be called to prompt the process to connect to the
* Command server if it is not already connected.
*/
- (oneway void) ecReconnect;
/** This method is designed for handling an orderly restart.<br />
* The default implementation calls -ecQuitFor:with: with minus one as
* the status code so that the Command server will start the process
* again.<br />
* The method is called automatically when the MemoryMaximum limit is
* exceeded (to gracefully handle memory leaks by restarting).<br />
* Subclasses may override this method to allow the shutdown process to be
* handled differently.
*/
- (oneway void) ecRestart: (NSString*)reason;
/** Return the timestamp at which this process started up (when the
* receiver was initialised).
*/
- (NSDate*) ecStarted;
/** Release a lock on the shared EcProcess after thread-safe updates to
* process-wide variables.
*/
- (void) ecUnLock;
/** This is ignored if the process is already quitting,
* otherwise it returns after setting the start time used by the
* -ecIsQuitting method and (if -ecQuitReason is not nil/empty)
* generating a log of why quitting was started.<br />
* Called automatically when the process starts shutting down.
*/
- (void) ecWillQuit;
/* Call these methods during initialisation of your instance
* to set up automatic management of connections to servers.
* You then access the servers by calling -(id)server: (NSString*)serverName.
*/
/** This is a convenience method equivalent to calling
* -addServerToList:for: passing nil as the second argument.
*/
- (void) addServerToList: (NSString*)serverName;
/** Adds the specified serverName to the list of named servers to which
* we make automatic distributed object connections.<br />
* By default the supplied serverName is taken as the name of the server to
* which the distributed objects connection is made, and the connection
* is to any host on the local network. However configuration in the
* user defaults system (using keys derived from the serverName) may
* be used to modify this behavior:
* <deflist>
* <term>serverNameName</term>
* <desc>Specifies the actual distributed objects port name to which the
* connection is made, instead of using serverName.</desc>
* <term>serverNameHost</term>
* <desc>Specifies the actual distributed objects host name to which the
* connection is made, instead of using an asterisk (any host).</desc>
* <term>serverNameBroadcast</term>
* <desc>Specifies that the server should actually be configured to be
* a broadcast proxy (see [EcBroadcastProxy]).<br />
* The value of this field must be an array containing the configuration
* information for the [EcBroadcastProxy] instance.<br />
* If this is defined then the serverNameName and serverNameHost values
* (if present) are ignored, and the connections are made to the
* individual servers listed in the elements of this array.</desc>
* </deflist>
* The argument anObject is an object which will be messaged when the
* connection to the server is established (or lost). The messages
* sent are those in the <em>RemoteServerDelegate</em> informal
* protocol.<br />
* If no object is specified, the receiver is used.<br />
* Once a server has been added to the list, it can be accessed using
* the -server: or -server:forNumber: method.
*/
- (void) addServerToList: (NSString*)serverName for: (id)anObject;
/** Removes the serverName from the list of server processes for which
* we automatically maintain distributed object connections.<br />
* See the addServerToList:for: metho for more details.
*/
- (void) removeServerFromList: (NSString*)serverName;
/** Deprecated; do not use.
*/
- (void) cmdAlert: (NSString*)fmt arguments: (va_list)args;
/** Deprecated; do not use.
*/
- (void) cmdAlert: (NSString*)fmt, ... NS_FORMAT_FUNCTION(1,2);
/** Archives debug log files into the appropriate subdirectory for the
* supplied date (or the files last modification date if when is nil).<br />
* Returns a text description of any archiving actually done.<br />
* The subdirectory is created if necessary.
*/
- (NSString*) ecArchive: (NSDate*)when;
/** Send a log message to the server.
*/
- (void) cmdAudit: (NSString*)fmt arguments: (va_list)args;
/** Send a log message to the server by calling the -cmdAudit:arguments: method.
*/
- (void) cmdAudit: (NSString*)fmt, ... NS_FORMAT_FUNCTION(1,2);
/** Handles loss of connection to the server.
*/
- (id) cmdConnectionBecameInvalid: (NSNotification*)notification;
/** Returns the path to the data storage directory used by this process
* to store files containing persistent information.
*/
- (NSString*) cmdDataDirectory;
/** Send a debug message - as long as the debug mode specified as 'type'
* is currently set.
*/
- (void) cmdDbg: (NSString*)type msg: (NSString*)fmt arguments: (va_list)args;
/** Send a debug message - as long as the debug mode specified as 'type'
* is currently set. Operates by calling the -cmdDbg:msg:arguments: method.
*/
- (void) cmdDbg: (NSString*)type
msg: (NSString*)fmt, ... NS_FORMAT_FUNCTION(2,3);
/** Send a debug message with debug mode 'basicMode'.<br />
* Calls the -cmdDbg:msg:arguments: method.
*/
- (void) cmdDebug: (NSString*)fmt arguments: (va_list)args;
/** Send a debug message with debug mode 'basicMode'.<br />
* Operates by calling the -cmdDebug:arguments: method.
*/
- (void) cmdDebug: (NSString*)fmt, ... NS_FORMAT_FUNCTION(1,2);
/** Called automatically in response to a local NSUserDefaults database change
* or in response to a configuration update from the Control server.<br />
* This is automatically called after -cmdUpdate: (even if the user defaults
* database has not actually changed), in which case the notification
* argument is nil.<br />
* An automatic call to this method is (if it does not raise an exception)
* immediately followed by a call to the -cmdUpdated method.<br />
* This method deals with the updates for any defaults registered using
* the +ecRegisterDefault:withTypeText:andHelpText:action:value: method, so
* if you override this to handle configuration changes, don't forget
* to call the superclass implementation.<br />
* If you wish to manage updates from the central database in a specific
* order, you may wish to override the -cmdUpdate: and/or -cmdUpdated method.
*/
- (void) cmdDefaultsChanged: (NSNotification*)n;
/** Deprecated; do not use.
*/
- (void) cmdError: (NSString*)fmt arguments: (va_list)args;
/** Deprecated; do not use.
*/
- (void) cmdError: (NSString*)fmt, ... NS_FORMAT_FUNCTION(1,2);
/** Flush logging information.
*/
- (void) cmdFlushLogs;
/** This message returns YES if the receiver is intended to be a client
* of a Command server, and NO if it is a standalone process which does
* not need to contact the Command server.<br />
* The default implementation returns YES, but subclasses may override
* this method to return NO if they do not wish to contact the Command
* server.
*/
- (BOOL) cmdIsClient;
/** Returns a flag indicating whether this process is currently connected
* it its Command server.
*/
- (BOOL) cmdIsConnected;
/** Returns YES is the process is running in test mode, NO otherwise.<br />
* Test mode is defined by the EcTesting user default.
*/
- (BOOL) cmdIsTesting;
/** Closes a file previously obtained using the -cmdLogFile: method.<br />
* Returns a description of any file archiving done, or nil if the file
* dis not exist.<br />
* You should not close a logging handle directly, use this method.
*/
- (NSString*) cmdLogEnd: (NSString*)name;
/** Obtain a file handle for logging purposes. The file will have the
* specified name and will be created (if necessary) in the processes
* logging directory.<br />
* If there is already a handle for the specified file, this method
* returns the existing handle rather than creating a new one.<br />
* Do not close this file handle other than by calling the -cmdLogEnd: method.
*/
- (NSFileHandle*) cmdLogFile: (NSString*)name;
/** Used by the Command server to send messages to your application.
*/
- (void) cmdMesgData: (NSData*)dat from: (NSString*)name;
/** This method is called whenever the Command server sends an instruction
* for your Command client process to act upon. Often the command has been
* entered by an operator and you need to respond with a text string.<br />