1 /*
2     Copyright (c) 2005-2017 Intel Corporation
3 
4     Licensed under the Apache License, Version 2.0 (the "License");
5     you may not use this file except in compliance with the License.
6     You may obtain a copy of the License at
7 
8         http://www.apache.org/licenses/LICENSE-2.0
9 
10     Unless required by applicable law or agreed to in writing, software
11     distributed under the License is distributed on an "AS IS" BASIS,
12     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13     See the License for the specific language governing permissions and
14     limitations under the License.
15 
16 
17 
18 
19 */
20 
21 // Header guard and namespace names follow OpenMP runtime conventions.
22 
23 #ifndef KMP_RML_OMP_H
24 #define KMP_RML_OMP_H
25 
26 #include "rml_base.h"
27 
28 namespace __kmp {
29 namespace rml {
30 
31 class omp_client;
32 
33 //------------------------------------------------------------------------
34 // Classes instantiated by the server
35 //------------------------------------------------------------------------
36 
37 //! Represents a set of omp worker threads provided by the server.
38 class omp_server: public ::rml::server {
39 public:
40     //! A number of coins (i.e., threads)
41     typedef unsigned size_type;
42 
43     //! Return the number of coins in the bank. (negative if machine is oversubscribed).
44     virtual int current_balance() const = 0;
45 
46     //! Request n coins.  Returns number of coins granted. Oversubscription amount if negative.
47     /** Always granted if is_strict is true.
48         - Positive or zero result indicates that the number of coins was taken from the bank.
49         - Negative result indicates that no coins were taken, and that the bank has deficit
50           by that amount and the caller (if being a good citizen) should return that many coins.
51      */
52     virtual int try_increase_load( size_type /*n*/, bool /*strict*/ ) = 0;
53 
54     //! Return n coins into the bank.
55     virtual void decrease_load( size_type /*n*/ ) = 0;
56 
57     //! Convert n coins into n threads.
58     /** When a thread returns, it is converted back into a coin and the coin is returned to the bank. */
59     virtual void get_threads( size_type /*m*/, void* /*cookie*/, job* /*array*/[] ) = 0;
60 
61     /** Putting a thread to sleep - convert a thread into a coin
62         Waking up a thread        - convert a coin into a thread
63 
64        Note: conversion between a coin and a thread does not affect the accounting.
65      */
66 #if _WIN32||_WIN64
67     //! Inform server of a tbb master thread.
68     virtual void register_master( execution_resource_t& /*v*/ ) = 0;
69 
70     //! Inform server that the tbb master thread is done with its work.
71     virtual void unregister_master( execution_resource_t /*v*/ ) = 0;
72 
73     //! deactivate
74     /** give control to ConcRT RM */
75     virtual void deactivate( job* ) = 0;
76 
77     //! reactivate
78     virtual void reactivate( job* ) = 0;
79 #endif /* _WIN32||_WIN64 */
80 };
81 
82 
83 //------------------------------------------------------------------------
84 // Classes (or base classes thereof) instantiated by the client
85 //------------------------------------------------------------------------
86 
87 class omp_client: public ::rml::client {
88 public:
89     //! Called by server thread when it delivers a thread to client
90     /** The index argument is a 0-origin index of the job for this thread within the array
91         returned by method get_threads.  Server decreases the load by 1 (i.e., returning the coin
92         back to the bank) after this method returns. */
93     virtual void process( job&, void* /*cookie*/, size_type /*index*/ ) RML_PURE(void)
94 };
95 
96 /** Client must ensure that instance is zero-inited, typically by being a file-scope object. */
97 class omp_factory: public ::rml::factory {
98 
99     //! Pointer to routine that creates an RML server.
100     status_type (*my_make_server_routine)( omp_factory&, omp_server*&, omp_client& );
101 
102     //! Pointer to routine that calls callback function with server version info.
103     void (*my_call_with_server_info_routine)( ::rml::server_info_callback_t cb, void* arg );
104 
105 public:
106     typedef ::rml::versioned_object::version_type version_type;
107     typedef omp_client client_type;
108     typedef omp_server server_type;
109 
110     //! Open factory.
111     /** Dynamically links against RML library.
112         Returns st_success, st_incompatible, or st_not_found. */
113     status_type open();
114 
115     //! Factory method to be called by client to create a server object.
116     /** Factory must be open.
117         Returns st_success or st_incompatible . */
118     status_type make_server( server_type*&, client_type& );
119 
120     //! Close factory.
121     void close();
122 
123     //! Call the callback with the server build info.
124     void call_with_server_info( ::rml::server_info_callback_t cb, void* arg ) const;
125 };
126 
127 } // namespace rml
128 } // namespace __kmp
129 
130 #endif /* KMP_RML_OMP_H */
131