live
UsageEnvironment.hh
Go to the documentation of this file.
1 /**********
2 This library is free software; you can redistribute it and/or modify it under
3 the terms of the GNU Lesser General Public License as published by the
4 Free Software Foundation; either version 3 of the License, or (at your
5 option) any later version. (See <http://www.gnu.org/copyleft/lesser.html>.)
6 
7 This library is distributed in the hope that it will be useful, but WITHOUT
8 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
9 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
10 more details.
11 
12 You should have received a copy of the GNU Lesser General Public License
13 along with this library; if not, write to the Free Software Foundation, Inc.,
14 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
15 **********/
16 // Copyright (c) 1996-2019 Live Networks, Inc. All rights reserved.
17 // Usage Environment
18 // C++ header
19 
20 #ifndef _USAGE_ENVIRONMENT_HH
21 #define _USAGE_ENVIRONMENT_HH
22 
23 #ifndef _USAGEENVIRONMENT_VERSION_HH
25 #endif
26 
27 #ifndef _NETCOMMON_H
28 #include "NetCommon.h"
29 #endif
30 
31 #ifndef _BOOLEAN_HH
32 #include "Boolean.hh"
33 #endif
34 
35 #ifndef _STRDUP_HH
36 // "strDup()" is used often, so include this here, so everyone gets it:
37 #include "strDup.hh"
38 #endif
39 
40 #ifndef NULL
41 #define NULL 0
42 #endif
43 
44 #ifdef __BORLANDC__
45 #define _setmode setmode
46 #define _O_BINARY O_BINARY
47 #endif
48 
49 class TaskScheduler; // forward
50 
51 // An abstract base class, subclassed for each use of the library
52 
54 public:
55  Boolean reclaim();
56  // returns True iff we were actually able to delete our object
57 
58  // task scheduler:
60 
61  // result message handling:
62  typedef char const* MsgString;
63  virtual MsgString getResultMsg() const = 0;
64 
65  virtual void setResultMsg(MsgString msg) = 0;
66  virtual void setResultMsg(MsgString msg1, MsgString msg2) = 0;
67  virtual void setResultMsg(MsgString msg1, MsgString msg2, MsgString msg3) = 0;
68  virtual void setResultErrMsg(MsgString msg, int err = 0) = 0;
69  // like setResultMsg(), except that an 'errno' message is appended. (If "err == 0", the "getErrno()" code is used instead.)
70 
71  virtual void appendToResultMsg(MsgString msg) = 0;
72 
73  virtual void reportBackgroundError() = 0;
74  // used to report a (previously set) error message within
75  // a background event
76 
77  virtual void internalError(); // used to 'handle' a 'should not occur'-type error condition within the library.
78 
79  // 'errno'
80  virtual int getErrno() const = 0;
81 
82  // 'console' output:
83  virtual UsageEnvironment& operator<<(char const* str) = 0;
84  virtual UsageEnvironment& operator<<(int i) = 0;
85  virtual UsageEnvironment& operator<<(unsigned u) = 0;
86  virtual UsageEnvironment& operator<<(double d) = 0;
87  virtual UsageEnvironment& operator<<(void* p) = 0;
88 
89  // a pointer to additional, optional, client-specific state
92 
93 protected:
94  UsageEnvironment(TaskScheduler& scheduler); // abstract base class
95  virtual ~UsageEnvironment(); // we are deleted only by reclaim()
96 
97 private:
99 };
100 
101 
102 typedef void TaskFunc(void* clientData);
103 typedef void* TaskToken;
104 typedef u_int32_t EventTriggerId;
105 
107 public:
108  virtual ~TaskScheduler();
109 
110  virtual TaskToken scheduleDelayedTask(int64_t microseconds, TaskFunc* proc,
111  void* clientData) = 0;
112  // Schedules a task to occur (after a delay) when we next
113  // reach a scheduling point.
114  // (Does not delay if "microseconds" <= 0)
115  // Returns a token that can be used in a subsequent call to
116  // unscheduleDelayedTask() or rescheduleDelayedTask()
117  // (but only if the task has not yet occurred).
118 
119  virtual void unscheduleDelayedTask(TaskToken& prevTask) = 0;
120  // (Has no effect if "prevTask" == NULL)
121  // Sets "prevTask" to NULL afterwards.
122  // Note: This MUST NOT be called if the scheduled task has already occurred.
123 
124  virtual void rescheduleDelayedTask(TaskToken& task,
125  int64_t microseconds, TaskFunc* proc,
126  void* clientData);
127  // Combines "unscheduleDelayedTask()" with "scheduleDelayedTask()"
128  // (setting "task" to the new task token).
129  // Note: This MUST NOT be called if the scheduled task has already occurred.
130 
131  // For handling socket operations in the background (from the event loop):
132  typedef void BackgroundHandlerProc(void* clientData, int mask);
133  // Possible bits to set in "mask". (These are deliberately defined
134  // the same as those in Tcl, to make a Tcl-based subclass easy.)
135  #define SOCKET_READABLE (1<<1)
136  #define SOCKET_WRITABLE (1<<2)
137  #define SOCKET_EXCEPTION (1<<3)
138  virtual void setBackgroundHandling(int socketNum, int conditionSet, BackgroundHandlerProc* handlerProc, void* clientData) = 0;
139  void disableBackgroundHandling(int socketNum) { setBackgroundHandling(socketNum, 0, NULL, NULL); }
140  virtual void moveSocketHandling(int oldSocketNum, int newSocketNum) = 0;
141  // Changes any socket handling for "oldSocketNum" so that occurs with "newSocketNum" instead.
142 
143  virtual void doEventLoop(char volatile* watchVariable = NULL) = 0;
144  // Causes further execution to take place within the event loop.
145  // Delayed tasks, background I/O handling, and other events are handled, sequentially (as a single thread of control).
146  // (If "watchVariable" is not NULL, then we return from this routine when *watchVariable != 0)
147 
148  virtual EventTriggerId createEventTrigger(TaskFunc* eventHandlerProc) = 0;
149  // Creates a 'trigger' for an event, which - if it occurs - will be handled (from the event loop) using "eventHandlerProc".
150  // (Returns 0 iff no such trigger can be created (e.g., because of implementation limits on the number of triggers).)
151  virtual void deleteEventTrigger(EventTriggerId eventTriggerId) = 0;
152 
153  virtual void triggerEvent(EventTriggerId eventTriggerId, void* clientData = NULL) = 0;
154  // Causes the (previously-registered) handler function for the specified event to be handled (from the event loop).
155  // The handler function is called with "clientData" as parameter.
156  // Note: This function (unlike other library functions) may be called from an external thread
157  // - to signal an external event. (However, "triggerEvent()" should not be called with the
158  // same 'event trigger id' from different threads.)
159 
160  // The following two functions are deprecated, and are provided for backwards-compatibility only:
161  void turnOnBackgroundReadHandling(int socketNum, BackgroundHandlerProc* handlerProc, void* clientData) {
162  setBackgroundHandling(socketNum, SOCKET_READABLE, handlerProc, clientData);
163  }
164  void turnOffBackgroundReadHandling(int socketNum) { disableBackgroundHandling(socketNum); }
165 
166  virtual void internalError(); // used to 'handle' a 'should not occur'-type error condition within the library.
167 
168 protected:
169  TaskScheduler(); // abstract base class
170 };
171 
172 #endif
unsigned char Boolean
Definition: Boolean.hh:25
virtual TaskToken scheduleDelayedTask(int64_t microseconds, TaskFunc *proc, void *clientData)=0
void TaskFunc(void *clientData)
virtual MsgString getResultMsg() const =0
u_int32_t EventTriggerId
#define NULL
virtual void internalError()
char const * MsgString
void turnOffBackgroundReadHandling(int socketNum)
void disableBackgroundHandling(int socketNum)
virtual void internalError()
virtual void deleteEventTrigger(EventTriggerId eventTriggerId)=0
void turnOnBackgroundReadHandling(int socketNum, BackgroundHandlerProc *handlerProc, void *clientData)
void * TaskToken
Boolean reclaim()
virtual void setBackgroundHandling(int socketNum, int conditionSet, BackgroundHandlerProc *handlerProc, void *clientData)=0
virtual void setResultMsg(MsgString msg)=0
virtual ~TaskScheduler()
virtual UsageEnvironment & operator<<(char const *str)=0
void BackgroundHandlerProc(void *clientData, int mask)
virtual void reportBackgroundError()=0
virtual void unscheduleDelayedTask(TaskToken &prevTask)=0
virtual void doEventLoop(char volatile *watchVariable=NULL)=0
TaskScheduler & fScheduler
virtual void setResultErrMsg(MsgString msg, int err=0)=0
virtual EventTriggerId createEventTrigger(TaskFunc *eventHandlerProc)=0
virtual ~UsageEnvironment()
TaskScheduler & taskScheduler() const
virtual void rescheduleDelayedTask(TaskToken &task, int64_t microseconds, TaskFunc *proc, void *clientData)
virtual void appendToResultMsg(MsgString msg)=0
virtual void triggerEvent(EventTriggerId eventTriggerId, void *clientData=NULL)=0
virtual void moveSocketHandling(int oldSocketNum, int newSocketNum)=0
#define SOCKET_READABLE
UsageEnvironment(TaskScheduler &scheduler)
virtual int getErrno() const =0