1 mike  1.1 /*
  2           **==============================================================================
  3           **
  4           ** Open Management Infrastructure (OMI)
  5           **
  6           ** Copyright (c) Microsoft Corporation
  7           ** 
  8           ** Licensed under the Apache License, Version 2.0 (the "License"); you may not 
  9           ** use this file except in compliance with the License. You may obtain a copy 
 10           ** of the License at 
 11           **
 12           **     http://www.apache.org/licenses/LICENSE-2.0 
 13           **
 14           ** THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 15           ** KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED 
 16           ** WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, 
 17           ** MERCHANTABLITY OR NON-INFRINGEMENT. 
 18           **
 19           ** See the Apache 2 License for the specific language governing permissions 
 20           ** and limitations under the License.
 21           **
 22 mike  1.1 **==============================================================================
 23           */
 24           
 25           #ifndef _omi_selector_h
 26           #define _omi_selector_h
 27           
 28           #include "config.h"
 29           #include <common.h>
 30           #include "sock.h"
 31           #include <base/list.h>
 32           #include <base/messages.h>
 33           
 34           BEGIN_EXTERNC
 35           
 36           #define SELECTOR_ADD        (1 << 0)
 37           #define SELECTOR_READ       (1 << 1)
 38           #define SELECTOR_WRITE      (1 << 2)
 39           #define SELECTOR_EXCEPTION  (1 << 3)
 40           #define SELECTOR_TIMEOUT    (1 << 4)
 41           #define SELECTOR_REMOVE     (1 << 5)
 42           #define SELECTOR_DESTROY    (1 << 6)
 43 mike  1.1 #define SELECTOR_IGNORE_READ_OVERLOAD    (1 << 7)
 44           
 45           typedef struct _Selector Selector;
 46           typedef struct _Handler Handler;
 47           
 48           struct _Handler
 49           {
 50               Handler* next;
 51               Handler* prev;
 52               Sock sock;
 53               MI_Uint32 mask;
 54               /* time when selector gets 'timeout' event - typically Time_Now() + ttl-in-usec;
 55                 '0' means 'ignore me' */
 56               MI_Uint64 fireTimeoutAt;  
 57               MI_Boolean (*callback)(Selector*, Handler*, MI_Uint32 mask, MI_Uint64 currentTimeUsec);
 58               void* data;
 59           };
 60           
 61           struct _Selector
 62           {
 63               struct _SelectorRep* rep;
 64 mike  1.1 };
 65           
 66           typedef void (*Selector_NotificationCallback)(void* self, Message* message);
 67           
 68           MI_Result Selector_Init(
 69               Selector* self);
 70           
 71           void Selector_Destroy(
 72               Selector* self);
 73           
 74           MI_Result Selector_AddHandler(
 75               Selector* self,
 76               Handler* handler);
 77           
 78           MI_Result Selector_RemoveHandler(
 79               Selector* self,
 80               Handler* handler);
 81           
 82           /* Used for quick shutdown procedure */
 83           MI_Result Selector_RemoveAllHandlers(
 84               Selector* self);
 85 mike  1.1 
 86           MI_Result Selector_ContainsHandler(
 87               Selector* self,
 88               Handler* handler);
 89           
 90           /* Runs socket processing loop;
 91               Parameters:
 92               self - selector
 93               timeoutUsec - time to run 
 94               
 95               Retunrs:
 96               OK - was stopped by StopRunning call
 97               FAILED - system call 'select' failed or no more sockets to monitor
 98               TIMEOUT - timeout reached 
 99           */
100           MI_Result Selector_Run(
101               Selector* self,
102               MI_Uint64 timeoutUsec);
103           
104           /* Informs selector's Run method that it should exit normaly.
105               Funciton is safe for calling from signal hanlder */
106 mike  1.1 MI_Result Selector_StopRunning(
107               Selector* self);
108           
109           /* Wakes up selector's thread 
110               Typical usage is to recalculate timeouts on handlers
111               when selector's Run is running in different thread */
112           MI_Result Selector_Wakeup(
113               Selector* self);
114           
115           /* 
116               * This function guaranties that callback is called in 'Run'/'IO' thread context,
117               * so no locking is required for accessing sokcet objects, updating buffers etc
118           */
119           MI_Result Selector_CallInIOThread(
120               Selector* self,
121               Selector_NotificationCallback  callback,
122               void* callback_self,
123               Message* message);
124           
125           /*
126               Informs selector that new Instance was created;
127 mike  1.1     Selector keeps track of number of Instances
128               so it can implement back-pressure (primitive) by
129               disabling read from oop and blocking other-thread providers
130           */
131           void Selector_NewInstanceCreated(
132               Selector* self,
133               Message* msg);
134           
135           
136           /*
137               Verifies if selector is in 'stressed' mode
138               and too many instance are alive now
139           */
140           MI_Boolean  Selector_IsStressed(
141               Selector* self);
142           
143           
144           /*
145               Sets flag 'allowEmptySelector' to allow 
146               'run' call on empty selector
147           */
148 mike  1.1 void Selector_SetAllowEmptyFlag(
149               Selector* self,
150               MI_Boolean allowEmptySelector);
151           
152           END_EXTERNC
153           
154           #endif /* _omi_selector_h */